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.
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:
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.
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
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