Akkroo
  1. Support
  2. Developers
  3. API
  4. versioning

Versioning

Numbering

The current API version is 1.1.5

API version 1.1.4 will be deprecated soon, please use latest version

API version numbering follows the pattern defined in Semantic Versioning v2.0.0:

MAJOR.MINOR.PATCH

Any minor versions will be backwards compatible. Only major releases will include breaking changes.

For Akkroo, this does not mean that the output or expected input of a minor update will be exactly the same as the previous version, but that the API will still support previous versions for request and response.

For example, if a field was removed between 1.2 > 1.3, if you send a request with version 1.2 and only accept a response from 1.2 then the API will handle that. However, if you instead send in the 1.3 format and accept the 1.3 format, it is expected you use the new field definitions.

Once the API reaches the next major version, Akkroo may drop backwards compatibility for older versions. This will be communicated to integrators well in advance.

How versioning works

Versioning on the Akkroo API is header based. You send Akkroo the version of the request content (Content-Type header), and the API response versions your application can handle (Accept header). If successful, Akkroo replies with the response and the version of the content.

    GET /api/company HTTP/1.1
Authorization: Basic <client credentials>
Content-Type: application/vnd.akkroo-v1.1.5+json
Accept: application/vnd.akkroo-v1.1.5+json
HTTP/1.1 200 OK
Content-Type: application/vnd.akkroo-v1.1.5+json
{
	"id":2,
	"lastModified":"Thu, 01 Aug 2013 10:01:27 +0100",
	"name":"Wexler Inc",
	"urlHash":"abcdefghijkl",
	"username":"wexler",
	"appPasscode":"12345"
}

If the API cannot fulfill the request you will receive an error.

For example, if you send an outdated Content-Type:

    GET /api/company HTTP/1.1
Authorization: Basic <client credentials>
Content-Type: application/vnd.akkroo-v0.9+json
Accept: application/vnd.akkroo-v1.1.5+json
HTTP/1.1 400 Bad Request
Content-Type: application/vnd.akkroo-v1.1.5+json
{
	"error":"APIVersion",
	"details":{
		"header":"Content-Type"
	},
	"message":"Request version is obsolete.  Please update your client"
}

Or an outdated Accept:

    GET /api/company HTTP/1.1
Authorization: Basic <client credentials>
Content-Type: application/vnd.akkroo-v1.1.5+json
Accept: application/vnd.akkroo-v0.9+json
HTTP/1.1 406 Bad Request
Content-Type: application/vnd.akkroo-v1.1.5+json
{
	"error":"APIVersion",
	"details":[],
	"message":"The API cannot support any of the Accepted response versions.  Please update your client"
}