Versions and compatibility

The API has one major version, /v1, and it only grows. An integration written today keeps working as new features arrive: nothing it relies on is renamed, removed or given a new meaning.

The version number

The API has a version number such as 1.62.0. It changes with every release:

• the minor number when something is added: an endpoint, a field, an event;
• the patch number when a description or a message text is corrected and nothing else changes.

You can read the version that an address serves at any time:

GET /v1/health also has a version, but it is the version of the Sursa release that serves the address, not the version of the API.

You do not choose a minor version: every request is served by the current one. Thanks to the rules below, that is safe.

What can change in /v1

These changes can come in any minor version. Write your integration so that they do not break it:

• New endpoints.
• New optional parameters and request fields. Requests without them behave as before.
• New fields in responses, objects and events.
• New values of enumerations in responses, such as a new card status or a new event type.
• New error codes, and new response headers.
• Limits that become less strict: a longer maximum length, a wider range.
• Reworded message texts of errors and reworded descriptions.

What your code must tolerate

• Ignore fields you do not know. Do not fail when a response has more fields than you expect, and do not use strict schemas that reject them.
• Accept enum values you do not know. Every enumeration in a response can grow. Treat an unknown value as "other" rather than as an error.
• Skip event types you do not know, both in webhooks and in streams.
• Handle unknown error codes by their HTTP status: see Errors.
• Do not depend on the order of fields in JSON objects, or on the exact text of messages.

What never changes in /v1

• A path, a parameter, a field or an enum value is never renamed or removed.
• The type of a field never changes, and a field never takes on a new meaning, such as new units.
• A request that is accepted today is not rejected later.
• The status code of a successful response stays the same.
• Error codes keep their meaning, and the detail field of error responses keeps its form.
• Event types are never renamed or removed, and their data only gains fields.

Breaking changes

If an incompatible change is ever needed, it is released as a new major version, such as /v2, next to /v1. /v1 keeps working unchanged, and the two run side by side.

When a route is going to be retired:

1. It is marked deprecated in the specification and listed in the changelog with the date it will be switched off.
2. Its responses carry the headers Deprecation: true and Sunset: <date>.
3. It keeps working for at least 180 days after the announcement. Organizations whose API keys use it are told in writing at least 90 days ahead.
4. After the sunset date, it answers 410 with the code api.gone for another 90 days.

Watch for the Deprecation header in your logs or monitoring: it is the earliest signal that a route you use is going away.

Staying informed

The changelog of this portal lists every release with what was added and what was deprecated. Before you upgrade your own integration, compare its code with the entries since the version you built it against.