The approach we've taken is to version our API on a per-resource basis. This allows us flexibility in developing new API features or introducing breaking changes without having to deprecate an entire version of our API, minimising the impact of non-breaking changes.

Initially, existing resources will remain as-is and will be frozen at "version 0".

Once we've enabled API versioning, the latest version of the requested resource will be returned unless an earlier version is explicitly requested using the Accept header.

A preview of our API versioning documentation is available as a GitHub Gist which explains this in more detail.

We'll provide more information on specific implementation details and resource MIME types as they become available.

API versioning.md

# API versioning
The Companies House API is versioned using MIME types and content negotiation.
You can request a specific version of a resource using the `Accept` request header,
and the resource version is returned in the `Content-Type` response header.
Each resource is versioned independently - there is no global API version number.
_Notes_: