API and data standards, along with relevant guidance published in the Technology Code of Practice help establish a data architecture for government and ensure interoperability.
New guidance on getting an API domain
The API domain naming guidance encourages development teams to use name-of-the-apis.api.gov.uk as their subdomain naming convention, for example vehicle-registration-number.api.gov.uk. Consistent naming conventions make APIs and resources easier to locate.
We’ve also included information on how to:
- get your domain set up and delegated
- secure your API domain
- manage your DNS provider regarding domain delegation
- get operations support
- manage your subdomain when setting up a developer hub, and how to name this hub
- manage domains for API documentation
API technical and data standards version 2
We’ve taken on board feedback from the API community and updated the API and data standards. These standards now bring more focus to areas such as reuse and managing personal data. We’ve improved wording and the structure, for example, all the sections on open data standards are together.
The new standards have more detail on how to respond to data requests, and how to design data fields with user needs in mind. They explain how and why you should allow your users to download bulk data. There’s also more information on when to use different methods of authentication and authorisation, and on token and permissions best practice.
We’ve added new sections on:
- linked data
- namespaces, sub-resources and query arguments
- providing a test service
The standards also advises documenting APIs using the open specification, OpenAPI 3, and this takes account of the recent decision by the Open Standards Board to encourage take-up of this specification across government.
Give us your feedback
Both the new standards and API domain guidance have already been through the cross-government content peer review group but we’re keen to hear from all those working in government API development.
We’re currently working on adding guidance on using GraphQL and aim to include this in our next update. If you have any experience working with GraphQL and would like to contribute to the guidance, please email API-Standards-Request@digital.cabinet-office.gov.uk.
Next up: Data standards and related workshops
We’re also working on a government data standard to further improve interoperability across government. To help shape the standard, we’ll be holding a series of workshops, first focussed on a data description language that can be used with a tabular data structure.
If you’d like to take part in these workshops, or get in touch regarding anything related to APIs and data standards please email API-Standards-Request@digital.cabinet-office.gov.uk or leave a comment below.