Instantly share code, notes, and snippets.

@ian-kent /API versioning.md Secret
Last active Sep 15, 2015

Embed
What would you like to do?

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
      }
    }
  ]
}
@nshumoogum

This comment has been minimized.

Show comment
Hide comment
@nshumoogum

nshumoogum Sep 15, 2015

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?

nshumoogum commented Sep 15, 2015

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment