Versioning and deprecation

A version in the address

The version is part of the address: https://api.mabellenote.com/v1. Version v1 only grows by addition. An incompatible change creates a new version, for instance /v2, which runs alongside the previous one.

What may happen within v1

These changes are not breaking and may happen at any time:

• a new operation;
• a new optional parameter;
• a new field in a response;
• a new value in an enumeration;
• a new event type;
• a new error code, on a new operation;
• a required parameter that becomes optional;
• a raised limit.

What never changes within v1

• An operation, a field or an enumeration value is never removed or renamed.
• The type or format of a field does not change.
• An optional parameter does not become required.
• A field that is always filled does not become optional or null.
• The meaning of a field, the status or code of an error, and the scope an operation requires stay the same.

Writing a robust integration

• Ignore fields you do not know.
• Every enumeration is open: plan a default handling for an unknown value.
• A documented field is always present, null when empty.
• Identifiers are opaque strings: do not interpret them.
• Dates are ISO 8601 strings in UTC, with milliseconds.

Beta operations

An operation marked “Beta” in the reference (x-stability: beta in the OpenAPI description) may still change before it is declared stable: it is not covered by the guarantees above. Read operations are stable; the event log, webhooks, writes and publishing to Google are in beta. The table below, taken from the OpenAPI description, gives the stability of each operation.

Deprecating a version

When a new major version ships:

1. The previous version keeps being served unchanged for at least 12 months.
2. Its responses carry the Deprecation (RFC 9745) and Sunset (RFC 8594) headers, the latter giving the end date, and a Link header to the changelog (rel="deprecation").
3. The owners and admins of accounts still using the previous version are told by email.
4. After the end date, the previous version answers 410 Gone, with an error that points to the migration guide.

Every change to the contract is dated in the API changelog.

OpenAPI description

GET /v1/openapi.json returns the version's OpenAPI 3.1 description, without a key. The lang parameter picks the language of the descriptions (en by default, or fr). Use it to generate a client or to import the API into a testing tool.