Versioning

Version strategy

The Speakap API is versioned following a non-standard version numbering scheme. It shares similarities with SemVer, but should not be mistaken for a fully semantic versioning system.

Our API version consists of three sequences: v[EPIC].[MAJOR].[MINOR] making up a uniquely identifiable number.

EPIC: Epic new features, major overhauls and rewrites

MAJOR: Major or loads of new features

MINOR: Small features, incompatibilities, patches and fixes

In contrast with semantic versioning systems we unfortunately do not guarantee the absence of breaking changes when the MINOR version is bumped, but in general we strive to keep our API backwards compatible with older versions.

Request

API consumers are able to manipulate the version of the API handling and serving their request. By default the latest version applies (currently v1.8.2).

There are two ways to affect the version used by our API:

Accept Header

The HTTP Accept header can be used to specify the preferred API version for handling your request. In the Accept header this is combined with the media type preferred for the response.

For the Speakap API the returned media or content type is always JSON, but can have different layout, structure and metadata.

Examples

Accept: application/vnd.speakap.api-v1.4+json+hal

Accept: application/vnd.speakap.api-v2.1+json;q=1,application/vnd.speakap.api-v1.5+json;q=0.8

The first example tells the server:

Please use API version v1.5 and respond with JSON HAL

The second example uses the q parameter to indicate the relative degree of preference between the two API versions deemed as acceptable.

Please use API version v2.1 or else fallback to version v1.5 and respond with vanilla JSON

Query parameter

Another way to tell the server to use a different API version is by providing a query parameter. Unlike the Accept header you need to specify an exact version number excluding all the media type information:

Example

http://api.speakap.io/whoami/?v=1.5.5

Response

In accordance with the HTTP specification our servers will return a “Precondition Failed” response if we cannot conform to the preconditions placed via the Accept header.

Status Codes

Code	Description
400	Improperly formatted or unsupported API version in query parameter: returns an Error object
412	Precondition Failed: returns an Error object