AthausDocs

REST API: version

The version is the path v1. The Athaus-Version header, the release, and what is never a break.

Last updated:

The version of the API is its path: v1. Inside v1 changes only add: new operations, new optional members, new values where the docs call a list open. A client ignores members it does not know. A change that breaks existing clients makes /v2, and /v1 then keeps running for at least 12 months next to it.

The Athaus-Version header

You do not have to send a header, and it tells you nothing you need. Every response names v1 in the header Athaus-Version and in GET /v1/me as apiVersion. If you send it, we accept v1 and 1.

curl https://api.athaus.ai/v1/me   -H "Authorization: Bearer ath_live_..."   -H "Athaus-Version: v1"

Every other value is a 400 with api_version_unsupported, so a client that asks for something unknown is told so. A key depends on no version.

The release

v1 is the version, 1.1 is the release: every response to a call with a valid key names it in the header Athaus-Release and in info.version of the OpenAPI document. It counts the additions inside v1 (1.0, 1.1, 1.2) and is only a name: no request can select a release, and nothing behaves differently by it. The releases are listed with their dates in What's new. A release is cut with one entry there and one bump of the constant API_RELEASE, in the pull request that ships the additions or in a small one after a batch.

What a break is

A member is removed or changes its meaning, a value of an enumeration is removed, a path disappears. That gets a new version. Until there is a break, there is only the one.

What is no break

This can happen at any time without a new version. Build your client to tolerate it: ignore unknown members, handle unknown values of an enumeration, do not read the cursor or the page token.

  • New resources and new operations.
  • New optional request parameters.
  • New fields in a response object.
  • New values in an enumeration. Clients must handle values they do not know.
  • New event types.
  • New error codes and new error types. Branch on a known code and treat all others by their HTTP status.
  • A change of the human-readable error message.
  • A change of the order of keys in an object.
  • A change of the content or the length of a cursor. A cursor is opaque.
  • A change of the length or the character set of an object ID.
  • New headers in a response.

Deprecation

The promise, from this version on: what goes away is deprecated first, at least 12 months before it ends. Responses then carry the headers Deprecation and Sunset, which name both dates, and the reference marks the element as deprecated. A deadline is never shortened. Nothing is deprecated today.

Keep reading

On this page