Listed here web-based application programming interface (API) standards guidance may help your organisation deliver the best possible services to users.
API technical and data standards (v2 – 2019)
Publish your APIs over the internet by default. Email api-standards-request@digital.cabinet-office.gov.uk if you think your APIs ought not to be published over public infrastructure.
Proceed with the Technology Code of Practice
Make fully sure your APIs match the requirements for the Technology Code of Practice (TCoP) by simply making sure they:
proceed with the Open Standards Principles of open access, consensus-based open process and licensing that is royalty-free
scale to enable them to maintain service level objectives and agreements when demand increases
Are stable so they can maintain service level objectives and agreements when dealing or changed with unexpected events
Are reusable where possible so the national government will not duplicate work
Proceed with the industry standard and where build that is appropriate that are RESTful, designed to use HTTP verb requests to manipulate data.
When handling requests, you need to use HTTP verbs for their specified purpose.
One of the benefits of REST is you a framework for communicating error states that it gives.
In certain full cases, it may not be applicable to construct a REST API, for example, if you are building an API to stream data.
You should use HTTPS when making APIs.
Adding HTTPS will secure connections to your API, preserve user privacy, ensure data integrity, and authenticate the server providing the API. The Service Manual provides more assistance with HTTPS.
Secure APIs Transport that is using Layer (TLS) v1.2. Do not use Secure Sockets Layer (SSL) or TLS v1.0.
There are multiple free and low-cost vendors that offer TLS certificates. rather make certain API that is potential can establish trust in your certificates. Make certain you have a process that is robust timely certificate renewal and revocation.
Your API may warrant linking your computer data together. You could make your API more programmatically accessible by returning URIs, and by using standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to recognize data that are certain
If your API returns data in response to an call that is HTTP you should utilize URIs when you look at the payload to determine certain data. Where appropriate, you should utilize specifications that use hypermedia, including CURIES, JSON-LD or HAL.
This will make it easier to find those resources. For instance, you could return a “person” object which links to a resource representing their company in the following way:
Your choice that is first for web APIs must be JSON where possible.
Only use another representation to build something in exceptional cases, like once you:
want to connect to a legacy system, as an example, one which only uses XML
will receive clear advantages from complying with a broadly adopted standard (for example, SAML)
We advice you really need to:
create responses as a JSON object rather than a wide range (JSON objects can contain arrays that are JSON – arrays can limit the ability to include metadata about results and limit the API’s capability to add additional top-level keys as time goes on
document your JSON object to make certain it really is well described, and so that it’s not treated as a sequential array
avoid unpredictable object keys such as those produced from data since this adds friction for clients
use consistent grammar case for object keys – choose under_score or CamelCase and become consistent
The government mandates utilising the ISO 8601 standard to represent date and time in your payload response. This can help people read the right time correctly.
Use a date format that is consistent. For dates, this appears like 2017-08-09 . For dates and times, make use of the form 58:07Z that is 2017-08-09T13 .
The European Union mandates utilizing the ETRS89 standard when it comes to scope that is geographical of. You can also use WGS 84 or other CRS coordinate systems for European location data as well as this.
Make use of the World Geodetic System 1984 (WGS 84) standard for the rest of the world. You can even use other CRS coordinate systems for the rest of the world as well as this.
You should use GeoJSON for the exchange of location information.
The Unicode Transformation Format (UTF-8) standard is mandatory for use in government when text that is encoding other textual representations of information.
Configure APIs to respond to ‘requests’ for data rather than ‘sending’ or ‘pushing’ data. This is why sure the API user only receives the information they might require.
When responding, your API must answer the request fully and specifically. For instance, an API should respond to the request “is this user married?” with a boolean. The solution should not return any longer detail than is needed and may depend on the customer application to correctly interpret it.
When designing your data fields, you should think about the way the fields will meet user needs. Having a technical writer in your team makes it possible to repeat this. It is possible to regularly test your documentation.
For instance, if you want to collect information that is personal in the dataset, before carefully deciding on the payload response, you may need to consider whether:
the look can deal with names from cultures which don’t have first and names that are last
the abbreviation DOB makes sense or whether it’s easier to spell out of the field to date of birth
DOB is reasonable when combined with DOD (date of death) or DOJ (date of joining)
It’s also wise to make sure you provide all of the relevant options. For example, the “marriage” field probably will have more than 2 states you intend to record: married , unmarried , divorced , widowed , estranged , annulled and so forth.
Dependent on that which you decide, you could pick the payload that is following a response:
When providing an Open Data API, you need to let users download whole datasets unless they contain restricted information. This gives users:
the ability to analyse the dataset locally
support when performing an activity access that is requiring your whole dataset (as an example, plotting a graph on school catchment areas in England)
Users must be able do my homework to index their copy that is local of utilizing their choice of database technology and then perform a query to meet their demands. This means future API downtime won’t affect them since they already have got all the info they want.
Using a record-by-record data API query to perform the same action would be suboptimal, both for the consumer and for the API. This is because:
rate limits would slow down access, or may even stop the whole dataset from downloading entirely
if the dataset is being updated at the time that is same the record-by-record download, users could get inconsistent records
In the event that you allow a user to download an entire dataset, you should consider providing an easy method for them to keep writing to date. For example you might live stream important computer data or notify them that new information is available to ensure API consumers know to download you API data periodically.
Don’t encourage users to keep datasets that are large up to now by re-downloading them since this approach is wasteful and impractical. Instead, let users download incremental lists of changes to a dataset. This enables them to keep their particular local copy up to date and saves them needing to re-download the entire dataset repeatedly.
There clearly wasn’t a recommended standard with this pattern, so users can try approaches that are different as:
encoding data in Atom/RSS feeds
using emergent patterns, such as for instance event streams employed by products such as for instance Apache Kafka
making use of open data registers
Make data obtainable in CSV formats in addition to JSON when you want to write bulk data. This is why sure users may use an array of tools, including software that is off-the-shelf to import and analyse this data.
Publish bulk data on data.gov.uk and work out sure there clearly was a prominent connect to it.
When your API serves personal or sensitive data, you must log if the data is provided and to whom. This can help you satisfy your desires under General Data Protection Regulation (GDPR), respond to data access that is subject, and detect fraud or misuse.
Use open access (no control) you do not need to identify your users, for example when providing open data if you want to give unfettered access to your API and . However, do keep in mind the risk of denial-of-service attacks.
Open access doesn’t mean you will be unable to throttle your API.
Consider the option of publishing open data on data.gov.uk in place of via an API.when working with data that are open not use authentication to help you maximise the employment of your API.