Records API for S2
POST /streams/{stream}/records
GET /streams/{stream}/records?seq_num=42&count=100
GET /streams/{stream}/records/tail
trim
command.
S2-Format
is used to indicate the desired encoding of these bytes when records are represented in JSON.
S2-Format: raw
or omit header.Use when your record data is valid Unicode. Zero overhead, human-readable. Cannot handle binary data safely.S2-Format: base64
Use when you are working with arbitrary bytes. Always safe. 33% overhead over the wire.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.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:
Content-Type
header to application/proto
and send a protobuf-encoded payload.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.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.S2-Session
) is a minimal protocol to encapsulate streaming append
and read
session semantics for the data plane. Until it is rolled out, sessions are supported via v1alpha gRPC and most SDKs.
len(headers) == 1 && headers[0].name == b""
.fence
with up to 36 UTF-8 bytes as payload to set a fencing token for the stream. An empty payload clears the token. Fencing is strongly consistent, and subsequent appends that specify a fencing token will be rejected if it does not match.
trim
with exactly 8 big-endian bytes as payload representing the desired earliest sequence number for the stream — we will call it the trim point. The effective trim point from the command is going to be max(existing_trim_point, min(provided_trim_point, my_seq_num + 1))
. Trimming is eventually consistent, and trimmed records may be visible for a brief period.
fence
and trim
commands.