API Versioning

The APIs support API versioning via the HTTP Accept and Content-type headers.

`Accept` header

The client uses the Accept header (which is mandatory in each request) to specify the desired API version.

Example Accept headers:

Accept: application/json - this requests using the latest API version

Accept: application/vnd.cogitocorp.v1+json - this requests using API version 1

Accept: application/vnd.cogitocorp.vX+json - this requests using API version X

`Content-type` header

The Admin Service server uses the Content-type header in each response to specify the API version used. If the request's Accept header contains a specific supported version, the response's Content-type header will contain that version. If the request's Accept header contains more than one version, the response's Content-type header will contain the latest supported version. If the request's Accept header contains a non-supported version, the server will send a 406 response.

Example Content-type headers:

Content-type: application/json - latest API version used

Content-type: application/vnd.cogitocorp.v1+json - API version 1 used

Content-type: application/vnd.cogitocorp.vX+json - API version X used

200Ok

400Bad Request; e.g. domain not included

401Unauthorized; user is not authenticated to use this service

403Forbidden; user is not authorized to use this service

404Not Found; domain does not exist

406Not Acceptable; unsupported media type in Accept header