Clients can interact with S2 using the v1 REST API, primarily with JSON bodies conforming to its OpenAPI spec.

​
Compression

To optimize network usage and improve performance, the service supports compressed request and response bodies using the following algorithms:

  • zstd (preferred)
  • gzip

Standard HTTP semantics around Content-Encoding and Accept-Encoding apply.

Not all responses may be compressed, even if Accept-Encoding is set to a supported algorithm. Clients must check the Content-Encoding header on each response to determine whether the body is compressed and which encoding was used.

​
Record data in JSON

The following pieces of record data are stored as bytes:

  • header.name
  • header.value
  • body

A custom header S2-Format is used to indicate the desired encoding of these bytes when records are represented in JSON.

raw

S2-Format: raw or omit header.

Use when your record data is valid Unicode.

Zero overhead, human-readable.

Cannot handle binary data safely.

base64

S2-Format: base64

Use when you are working with arbitrary bytes.

Always safe.

33% overhead over the wire.

You can write using one format and read with another. When reading raw, S2 is interpreting the stored bytes as UTF-8. This will be a potentially-lossy conversion if it was not also written as raw, or as base64-encoded valid UTF-8.

​
Protobuf messages

Data plane endpoints to Append and Read records also support protobuf bodies. This helps avoid the base64 encoding tax compared to binary data in JSON messages.

To send and receive protobuf:

  • Set the Content-Type header to application/proto and send a protobuf-encoded payload.
  • Set the Accept header to application/proto to receive a protobuf-encoded response. The response will include the Content-Type: application/proto header if the server returns a protobuf.

Type definitions are available in git and Buf.

Sending Accept: application/proto request header only guarantees a protobuf response in case of a success (HTTP 200). Other status codes are always accompanied by JSON bodies.

​
Sessions

​
SSE

The retrieve records endpoint supports server push with Server-Sent-Events (SSE).

Clients can request an SSE response by setting the Accept: text/event-stream header.

curl --request GET \
  --url 'https://hello-world.b.aws.s2.dev/v1/streams/test/records?seq_num=0' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'Accept: text/event-stream'
event: ping
data: {"timestamp":1748357201}

​
S2S

S2-Session is a minimal protocol to encapsulate streaming session semantics for the data plane. It enables support for protobuf messaging and pipelined appends with an ordering guarantee.

S2S is in development and details will be available soon. In the meantime, v1alpha gRPC continues to be supported via the official SDKs.