Versioning & Deprecation

Versioning

Our APIs are versioned via a major version in the path, for example /exp/v1/documents. Only backwards-compatible changes will be made within this path version, such as:

• Addition of a new optional model field
• Addition of a new API endpoint
• Addition of optional request parameters

We will avoid backwards-incompatible changes where possible, but in the case they are necessary, we will release a new path (major) version, for example /exp/v2/documents. This may include changes such as:

• Removal or renaming of models and fields
• Removal of API endpoints
• Addition of required request parameters

One exception to this would be ENUM fields. While adding values to ENUM fields is considered a breaking change, there may be cases where we do this. However, we will only do this with strong coordination with any clients that would be affected by the change and therefore utilising the new value. We will never add ENUM values that would affect unsuspecting users.

Deprecation

Over the course of an APIs lifecycle, we may choose to deprecate it. This means it will no longer receive support and updates, and is usually used when there is a new API or version which should be migrated to.

If an API or endpoint is due for deprecation, all responses will contain the header Deprecation. For example:

Deprecation: Sun 01 Jan 2023 23:59:59 GMT

This would indicate that the API will be deprecated as of the 1st January 2023. It should be noted that while it will no longer be supported a deprecated API will continue to function after it's deprecated date, until it is sunset (see below).

Sunsetting

Sunsetting an API is the act of making the API no longer available to use. Similarly to deprecation, when an API or endpoint is due to be sunset, it will contain the header Sunset. For example:

Sunset: Sat 01 Apr 2023 23:59:59 GMT

This would indicate that the API will no longer be available after the 1st April 2023, any users must migrate before this date. We will of course review usage and communicate with our API users to assist in migration to newer APIs where possible.