API Description

2016-11-11

Available versions

• Version 1 − Stable version

API contract

Versioning

Stable versions

Our Application Programming Interface (API) is versioned. Version numbers conform to the regular expression /^v[0-9]+$/, which is to say, lowercase letter v followed by one or more digits. There are no major / minor version numbers, and no tags such as -rc (release candidate), -alpha, -beta, etc. When a new version is deemed ready for public use, it gets assigned a positive, integer number and published.

Development version

All development happens under version 0 (v0). This is a special version, although it is usually accessible to the public, its use is highly discouraged and totally unsupported.

Version stability

We guarantee that any API calls described in our documentation for a given version will work for that version’s entire lifetime, and that responses to those calls will conform to the format, and contain at least the attributes described when the version was originally published. Do note that extra information may be present in latter iterations (such as in the form of additional JSON attributes).

Intra-version evolution

API versions may evolve, for example by adding extra options, output formats, and even new endpoints. Essentially, the API is forward-compatible, in the sense that a client implementation that worked on day one should continue to work as long as the API version number is not incremented.

Version increments

When, in order to satisfy user needs or development goals, we need to make breaking changes to the API, the API version number is incremented.

A more recent version will always be higher-numbered than an older one. Number increases are not necessarily by unity or monotonic—we may skip version numbers for whatever reason.

There are no guarantees of compatibility whatsoever between different versions. A version increase may (or may not) require a complete rewrite of client code.

Version deprecation

The release of a newer version does not imply anything about the obsolescence of earlier code. For instance, a newer version might be released in order to support an alternative interface incompatible with an existing one, without however causing the latter to be deprecated.

If on the other hand, we deem it necessary to deprecate an older API version, we undertake to announce the change with sufficient time, liaise with affected users, and give them ample opportunity to adapt their clients, taking into consideration the particularities of their cases.

Backend

The backend code tends to evolve much faster than the interface. API and backend version numbers are not coupled in any way. Information about the backend version in use may be available in the response as an HTTP header—look for X-WXT-Describe.