API Versioning
Each API supports an API version using the HTTP accept and content-type headers to convey versioning information.
Accept header
The client will use the HTTP accept header in a request to define the desired API version. If more than one media type is included in the header, the latest supported version will be used.
Example headers:
Default header that uses the latest API version:
accept: application/json
Header requesting the use of the first API version:
accept: application/vnd.cogitocorp.v1+json
Header requesting the use of the "X" API version:
accept: application/vnd.cogitocorp.vX+json
Content-type header
The Cogito server will use the HTTP content-type header in responses to define the API version used.
Examples
| accept (Request) | content-type (Response) | Response | Comment |
|---|---|---|---|
| application/json | application/json | 2xx | Server will use the latest version of the API |
| application/vnd.cogitocorp.v1+json | application/vnd.cogitocorp.v1+json | 2xx | Server will use version v1 of the API (even if server supports v2) |
| application/vnd.cogitocorp.v2+json | application/vnd.cogitocorp.v2+json | 2xx | Server will use version v2 of the API |
| application/json,application/vnd.cogitocorp.v2+json | application/vnd.cogitocorp.v2+json | 2xx | Server will use version v2 of the API |
| application/vnd.cogitocorp.v1+json, application/vnd.cogitocorp.v2+json | application/vnd.cogitocorp.v2+json | 2xx | If the server supports v2, it will be used; otherwise v1 will be used |
| application/vnd.cogitocorp.v3+json | application/json | 406 | If server does not support the requested version, a 406 error will be returned |
| unsupported media type or media type does not conform to RFC2046 | N/A (empty body) | 406 | In case of an unsupported media type or invalid media type, server will send 406 response |
Updated over 2 years ago