Table of contents

Version history

Current version

v1 is the current version of the API.

You can access v1 of the API using these base URLs:

  • https://{register}
  • https://{register}

API release cycle

next is a preview of the upcoming API before that API becomes stable. You should not use it in production, since the API may change without notice.

The release schedule is:

  1. The GOV.UK Registers team releases the next API. You can use the next version of the API to test against backwards-incompatible changes before next becomes the stable API.
  2. When the next API is stable, it will be renamed to the next version (eg v2).
  3. After a set amount of time, the previous version of the API is deprecated.

You can access the next version of the API using this base URL:

  • https://{register}

Upgrading from v1 to next

Data model changes

The registers data model has changed since v1 of the API:

  • The term “blob” replaces the term “item” (RFC-14).
  • Registers no longer have “indexes” (RFC-20).
  • Records are no longer defined in terms of entries (RFC-25).

These changes mean that:

  • you now access the resource at /blobs/{blob-hash} instead of /items/{item-hash}
  • the item-hash attribute has been replaced by blob-hash
  • blob-hash is computed differently from the existing item-hash vaues, so if your code relies on updates, you should fetch all the data again after updating to this version of the API
  • the index-entry-number attribute no longer exists (use entry-number instead)
  • /entries/{entry-number} now returns a single object instead of an array of objects

  • /records/{key} now returns a flat record object with the entry key using the reserved field _id, instead of an object indexed by the entry key. In addition the entry-number and entry-timestamp have been removed from the object. If you require these you can get them using the /records/{key}/entries endpoint.

  • /records now returns an array of record objects, instead of an object indexed by entry key

  • /records/{field-name}/{field-value} has moved to name and value query parameters on /records, for example /records/local-authority-type/CTY has moved to /records?name=local-authority-type&value=CTY

New /blobs endpoint

You can use the /blobs endpoint to retrieve multiple blobs in a single request. This is faster than fetching blobs one by one.

/blobs is paginated, and by default it returns the first 100 blobs in the register. To fetch more data, query the URL provided in the Link header that has rel=next.

Blobs are returned in the order they were added to the register. This guarantees that complete pages will always contain the same blobs.

New /context endpoint

The context endpoint replaces /register (RFC 18).

This endpoint exposes extra metadata about the schema of a register. Each register field is now an object containing id, datatype and cardinality attributes.

The following attributes are no longer included in the response:

  • phase (use the start-date/end-date attributes of the status object to determine whether the register is active or retired)
  • last-updated (this is the entry-timestamp of the last entry returned by /entries)
  • registry

Hash values are formatted using multihash

We now use the multihash format to format hash values. This means that blob hashes are now prefixed with the string 1220 instead of sha-256:.