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:

• the MIME types and resource examples used here are for demonstration purposes only, you should consult the API resource documentation for up to date MIME types
• existing API resources will be frozen at v0 and will be maintained for 3 months

Example

This request returns the latest version of a Company Profile resource:

GET /company/12345678
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/vnd.companieshouse.company-profile.v1+json

{
  "company_number": "12345678"
}

Version changes

Version numbers will be incremented for breaking changes, for example:

• removing or renaming a field
• changing a field data type
• changing the structure of a nested field

Non-breaking changes will not increment the version number, for example:

• adding additional fields

Default versions

The default behaviour is to return the latest version of a resource, when:

• no Accept header is provided with the request
• the Accept header is set to application/json or */*

HTTP response codes

For a valid Accept header, the HTTP response codes are specified in the API endpoint documentation.

If the Accept header MIME type is invalid, a 406 response is returned:

GET /company/12345678
Accept: application/vnd.companieshouse.company-profile.v999+json

HTTP/1.1 406 Not Acceptable

If the Accept header MIME type has recently expired, a 410 response is returned:

GET /company/12345678
Accept: application/vnd.companieshouse.company-profile.v0+json

HTTP/1.1 410 Gone

Collections

API endpoints which return collections of resources (e.g. Search, Officers, or Charges) have two MIME types.

Note: some existing collections use a non-standard "legacy" collection schema. These will be migrated to a new collection schema as soon as possible.

The top-level MIME type specifies the collection version and defines the outer fields (e.g. items_per_page) which are consistent across all collection-based endpoints.

An additional item-type parameter specifies the version of the resources inside the collection - i.e., each resource inside the items array.

For example, this request returns a collection of Company Officers using the latest version of a Company Officer resource and the latest Collection type:

GET /company/12345678/officers
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/vnd.companieshouse.collection.v1+json;
   item-type= application/vnd.companieshouse.company-officer.v1+json

{
  "limit": 10,
  "items": [
    {
      "date_of_birth": "1950-10-01"
    }
  ]
}

The two MIME types are independent, and any combination of valid collection or resource versions will be accepted.

This example uses the v1 collection type with a v2 resource type:

GET /company/12345678/officers
Accept: application/vnd.companieshouse.collection.v1+json;
   item-type= application/vnd.companieshouse.company-officer.v2+json

HTTP/1.1 200 OK
Content-Type: application/vnd.companieshouse.collection.v1+json;
   item-type= application/vnd.companieshouse.company-officer.v2+json

{
  "limit": 10,
  "items": [
    {
      "date_of_birth": {
        "month": 10,
        "year": 1950
      }
    }
  ]
}

This example uses the v2 collection type with a v1 resource version:

GET /company/12345678/officers
Accept: application/vnd.companieshouse.collection.v2+json;
   item-type= application/vnd.companieshouse.company-officer.v1+json

HTTP/1.1 200 OK
Content-Type: application/vnd.companieshouse.collection.v2+json;
   item-type= application/vnd.companieshouse.company-officer.v1+json

{
  "items_per_page": 10,
  "items": [
    {
      "date_of_birth": "1950-10-01"
    }
  ]
}

Deprecation

When a resource version is deprecated its expiry date will be provided in a CH-Expiry-Date response header.

This provides the date the resource version will become unavailable, which will typically be 3 months after the deprecation date.

For example:

GET /company/12345678
Accept: application/vnd.companieshouse.company-profile.v1+json

HTTP/1.1 200 OK
Content-Type: application/vnd.companieshouse.company-profile.v1+json
CH-Expiry-Date: 2016-01-01;
           rel= application/vnd.companieshouse.company-profile.v1+json

{
  "company_number": "12345678"
}

The rel parameter specifies which MIME type has been deprecated.

The CH-Expiry-Date header may be provided multiple times, for example where a collection type and resource type are both deprecated:

GET /company/12345678/officers
Accept: application/vnd.companieshouse.collection.v1+json;
   item-type= application/vnd.companieshouse.company-officer.v1+json

HTTP/1.1 200 OK
Content-Type: application/vnd.companieshouse.collection.v1+json;
   item-type= application/vnd.companieshouse.company-officer.v1+json
CH-Expiry-Date: 2016-07-01;
           rel= application/vnd.companieshouse.collection.v1+json
CH-Expiry-Date: 2016-01-01;
           rel= application/vnd.companieshouse.company-officer.v1+json

{
  "items_per_page": 10,
  "items": [
    {
      "date_of_birth": {
        "month": 10,
        "year": 1950
      }
    }
  ]
}

I assume the CH-Expiry-Date and rel is returned in the response only when an api user sends in a request using a relative version that is about to become unavailable?