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.


accept (Request)content-type (Response)ResponseComment
application/jsonapplication/json2xxServer will use the latest version of the API
application/vnd.cogitocorp.v1+jsonapplication/vnd.cogitocorp.v1+json2xxServer will use version v1 of the API (even if server supports v2)
application/vnd.cogitocorp.v2+jsonapplication/vnd.cogitocorp.v2+json2xxServer will use version v2 of the API
application/json,application/vnd.cogitocorp.v2+jsonapplication/vnd.cogitocorp.v2+json2xxServer will use version v2 of the API
application/vnd.cogitocorp.v1+json, application/vnd.cogitocorp.v2+jsonapplication/vnd.cogitocorp.v2+json2xxIf the server supports v2, it will be used; otherwise v1 will be used
application/vnd.cogitocorp.v3+jsonapplication/json406If server does not support the requested version, a 406 error will be returned
unsupported media type or media type does not conform to RFC2046N/A (empty body)406In case of an unsupported media type or invalid media type, server will send 406 response