API stability

Full API compatibility is guaranteed for version 0.5 and upwards. The current development version (master) contains the definitive API for the 0.5 release. This also means that there is no compatibility between the 0.4.x and 0.5.x releases.

API versioning

Starting with the 0.5 release, we have introduced a stable API versioning scheme. All services have a GetServiceDescription method, which returns some information about the service. This includes an ApiVersion field, which indicates the current version of the API. This is a global version number for all our APIs, which increases with all added functions. The fact that it is global implies that the API level in each service gets updated when we add a function to one service. This means that for a single service there doesn't have to be a change between API levels. We try to update it with each new function in development versions too (so the difference in API level between two feature releases isn't necessarily 1).

A list of changes in each API version can be found below.

• API version 4: This will be the API version of our first API stable release, 0.5.0.

API compatibility guarantee

From now on, the API will only be changed in backwards-compatible ways. This implies that:

• We won't change names or types of parameters, remove them, reorder them or make optional parameters required.
• We won't remove or rename fields in the returned structures.
• We won't change the type of returned fields.
• We won't change the name, returntype or URL of existing methods.
• We can add new optional parameters at the end of the parameter list.
• We can add new fields to returned structures.
• We can add new methods to all APIs.
• We can add new services.
• We can move fields from the Detailed variant to the Basic variant (this boils down to adding a field to the Basic class).
• We will change the version number of our DLLs.

Data like the transcoder profiles, transcoding targets, config file format, libraries and zeroconf configuration are excluded from the API freeze. Please contact us if you want to depend on these - we can probably arrange something.