REST API can change throughout the system life.
•In order to handle changes, the API version is included in the REST API URIs.
•Our REST API handles semantic versioning as defined in semver.org
oAPI versioning is implemented as v[MAJOR].[MINOR]
oThe MAJOR version is changed when there is an interface break and the API is incompatible with the previous version.
oThe MINOR version is changed whenever there is a change in payload or parameters, but the update is backward-compatible.
•Our servers are supporting the two latest MAJOR versions in parallel.
oThis avoids synchronizing the delivery of a new version of API and its related clients.
Usage:
The examples below are for the Ticket application, which has API versions 2.3 and 1.5. |
•If the client does not specify an interface version, it is redirected (HTTP redirection) to the latest version
→ GET /tickets ← 307 Temporary Redirect Location: /v2/tickets → GET /v2/tickets ← 200 OK |
•The client can specify only the MAJOR version or both MAJOR.MINOR
GET /v2/tickets <=> GET /v2.3/tickets <=> GET /tickets |
•If the client specifies a version, v1.2 or v1, the code of the latest minor version related to the specified major version will be executed.
GET /v2.1 will in fact execute the v2.3 code |
•If the interface version does not exist (e.g., v2.4) or is too old (v0), the server will answer with 404 Not Found.
Clients are advised to ask for the precise interface on which they are developed on. |
