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, their six settles and renew, 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, queue uids, leases, handles and cursors opaque and never longer than the maxima in limits, which are fixed: size storage for them.
  • 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.
  • A body on a response that had none. Ignore a body you do not read.
  • 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.
  • New statuses on an operation. Read an unknown status by its class: a 4xx is a verdict unless its kind says otherwise, a 5xx follows retrying a change.
  • New values in a string enum: a message or queue state, a limit name in spool_full. Treat an unknown value as "other"; a message in a state you do not know is not yours to act on.

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 console's own API. The console talks to account.spooler.sh, which these pages do not document; it serves the console and changes with it, without notice. The promise covers what the API reference documents and nothing else.
  • 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.