Appearance

The v1 promise ​

Last updated 

Every path on this site sits under /v1. That segment is a promise: a client written against what these pages document keeps working, without changes, for as long as v1 is served.

What stays ​

  • Every operation. Its method and path, its parameters, its request and response shapes, the Spooler-* headers it takes and returns, and the meaning of each status and kind in errors.
  • The delivery contract. At least once, leases and their five settles, what a 201 and a 204 mean, retention, no ordering guarantee, and what a primary change drops — delivery and replication.
  • Value formats. Durations as integers with the unit in the name, timestamps as RFC 3339 UTC, message ids, lease tokens and cursors opaque.
  • Fixed bounds. A bound in limits may go up under v1; it never goes down.

What may be added ​

Additions are not breaking, and a client must tolerate them:

  • New operations, and new optional parameters and headers. A request that omits them behaves as before.
  • New fields in JSON responses. Decode the fields you use and ignore the rest.
  • New Spooler-* response headers.
  • New error kinds under an existing status. Match on the status first and on the kinds you handle; read an unknown kind the way its status alone reads.

What is not covered ​

  • Plan limits. They are per plan and change with the plan, not with the API; the values in force are on limits.
  • Behaviour these pages do not state. If confirming a claim would take reading the server, it is not promised.
  • The evaluation image's differences from the hosted API, listed on running locally. Everything else about the image follows v1.

How a breaking change ships ​

A change that would break a v1 client ships under a new segment, /v2, served beside v1. Removing an operation, a field, a header, or a kind, changing a type or a meaning, and lowering a bound are all breaking. v1 keeps being served for at least six months after v2 is announced here, with its end date published at the announcement.

A deprecation under v1 is a note on the operation's page, not a change in behaviour: a deprecated operation keeps working until v1 ends.