API Versioning and Deprecation

Versioning

We use URI Path versioning, prefixing all endpoints with a simple, incrementing version string (v1). All routes in a resource should have their versions increased at the same time, though this will usually only involve adding additional routes in your gateway.

/v1/myresources/*
/v2/myresources/*

Deprecation

Breaking API changes are inevitable. Should a deprecation become necessary, it is most convenient to use a common pattern for communication and documentation. For this purpose, we will use RFC-8594 and RFC-8288 to communicate the expected deprecation date, as well as any remediation documentation. This is there to help your consumers, as they can update their code at their own pace, and to help you, as it simplifies management and communication around that API.

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2018 23:59:59 GMT
Link: </docs/deprecation>; rel="sunset"; title="Deprecation Notice"

Breaking Changes

The following is a table of changes and whether they are considered ‘breaking’. A simple rule of thumb is that the “addition” of something is not considered breaking, while “changing” something is.

Any time a breaking change is introduced, we must follow the appropriate expand/contract change management process.

The Sunset Header

Sunset: Sat, 31 Dec 2018 23:59:59 GMT

As per RFC-8594, every endpoint that is flagged for deprecation must include this header, which specifies the date after which the endpoint will no longer be available. This allows clients to plan for the change and update their code accordingly.

The Link Header

If documentation is available describing the deprecation and the steps to take to update, you should use RFC-8288 to include include a Link header in your API response. This will allow our API clients to notify their authors and/or users that an out-of-date API is still in use, and that they should update their code and/or SDK.

Link: </target/url>; rel="sunset"; title="Human Readable Title"