API versioning

Global API version
The global API version is part of the path. Example. It is incremented whenever a stable end point is changed in a backwards-incompatible way. A change in the major version is a disruptive event. For this reason, we try hard to avoid changing the major version.

End point stability
Each API end point is marked with a stability class: Stable, unstable or experimental.

Stable
Stable end points are guaranteed to not change in incompatible ways. This means that the basic interface as documented by the spec is not going to change. Any changes in the structure of the returned content will be clearly indicated by the mime type.

Unstable
End points marked as unstable can change in incompatible ways without incrementing the major API version, but we'll reach out to users and make a strong effort to avoid breaking existing consumers.

Experimental
Experimental end points can change in incompatible ways at any time.