API technical and data standards (v2 – 2019)
Publish your APIs over the internet by default. Email [email protected] if you were to think your APIs should not be published over public infrastructure.
Stick to the Technology Code of Practice
Make sure your APIs fulfill the requirements associated with Technology Code of Practice (TCoP) by simply making sure they:
stick to the Open Standards Principles of open access, consensus-based open process and royalty-free licensing
scale so that they can 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 that the government will not duplicate work
Stick to 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 should use HTTP verbs for his or her specified purpose.
One of the benefits of REST is you a framework for communicating error states that it gives.
In certain full cases, may possibly not be applicable to construct a REST API, for instance, if you’re building an API to stream data.
You need to use HTTPS when creating 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 help with HTTPS.
Secure APIs Transport that is using Layer (TLS) v1.2. Do not use Secure Sockets Layer (SSL) or TLS v1.0.
You will find multiple free and low-cost vendors that offer TLS certificates. rather make certain potential API users can establish rely upon your certificates. Make sure you have a robust process for timely certificate renewal and revocation.
Your API may warrant linking your data together. You may make your API more programmatically accessible by returning URIs, and also by using standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to recognize certain data:
As soon as your API returns data as a result to an call that is HTTP you should utilize URIs in the payload to determine certain data. Where appropriate, you need to use specifications which use hypermedia, including CURIES, JSON-LD or HAL.
This makes it more straightforward to find those resources. For instance, you might return a “person” object which links to a reference representing their company in the way that is following
Your choice that is first for web APIs should be JSON where possible.
Only use another representation to build something in exceptional cases, like whenever you:
need certainly to hook up to a legacy system, for instance, one that only uses XML
will receive advantages that are clear complying with a broadly adopted standard (for instance, SAML)
We advice you ought to:
create responses as a JSON object rather than an array (JSON objects can contain JSON arrays) – arrays can limit the ability to include metadata about results and limit the API’s capacity to add additional top-level keys in the foreseeable future
document your JSON object to make sure it is well described, and thus that it is not treated as a array that is sequential
Avoid object that is unpredictable like those produced from data since this adds friction for clients
Use grammar that is consistent for object keys – choose under_score or CamelCase and stay consistent
The government mandates utilizing the ISO 8601 standard to represent time and date in your payload response. This helps people browse the right time correctly.
Use a consistent date format. For dates, this appears like 2017-08-09 . For dates and times, use the form 58:07Z that is 2017-08-09T13 .
The European Union mandates with the ETRS89 standard when it comes to geographical scope of Europe. You are able to use WGS 84 or other CRS coordinate systems for European location data along with this.
Make use of the World Geodetic System 1984 (WGS 84) standard for the remainder world. You are able to use other CRS coordinate systems for the rest of the world along with this.
You should use GeoJSON for the exchange of location information.
The Unicode Transformation Format (UTF-8) standard is mandatory for usage in government when encoding text or other textual representations of information.
Configure APIs to respond to ‘requests’ for data as opposed to ‘sending’ or ‘pushing’ data. This makes sure the API user only receives the information they might need.
When responding, your API must answer the request fully and specifically. As an example, an API should react to the request “is this user married?” with a boolean. The solution must not return any more detail than is required and may depend on your client application to interpret it correctly.
When designing your computer data fields, you should look at the way the fields will meet user needs. Having a writer that is technical your team will allow you to do that. It is possible to regularly test thoroughly your documentation.
For example, if you wish to collect information that is personal in your dataset, before making a decision in your payload response, you may want to consider whether:
the look can cope with names from cultures which don’t have first and last names
the abbreviation DOB makes sense or whether it’s more straightforward to spell out the field up to now of birth
DOB is sensible when along with DOD (date of death) or DOJ (date of joining)
You should also make custom writings sure you provide most of the relevant options. For instance, the “marriage” field probably will have significantly more than 2 states you intend to record: married , unmarried , divorced , widowed , estranged , annulled and so on.
Based on everything you decide, you may pick the payload that is following a response:
When providing an Open Data API, you need to let users datasets that are download whole they contain restricted information. This provides users:
the capacity to analyse the dataset locally
support when performing a job access that is requiring your whole dataset (for instance, plotting a graph on school catchment areas in England)
Users should be able to index their local copy of data utilizing their range of database technology and then perform a query to generally meet their demands. This means that future API downtime won’t affect them they need because they already have all the data.
Using a record-by-record data API query to perform the action that is same be suboptimal, both for the user and for the API. The reason being:
rate limits would slow down access, or may even stop the dataset that is whole downloading entirely
in the event that dataset has been updated at the same time with the record-by-record download, users may get inconsistent records
In the event that you allow a user to download a complete dataset, you should think about providing an easy method for them to keep writing to date. As an example you can live stream important computer data or notify them that new data is available to ensure API consumers know to download you API data periodically.
Don’t encourage users to help keep datasets that are large to date by re-downloading them as this approach is wasteful and impractical. Instead, let users download incremental lists of changes to a dataset. This allows them to keep their very own local copy up to date and saves them needing to re-download the complete dataset repeatedly.
There clearly wasn’t a recommended standard for this pattern, so users can try different approaches such as:
encoding data in Atom/RSS feeds
using emergent patterns, such as for example event streams employed by products such as Apache Kafka
making utilization of open data registers
Make data obtainable in CSV formats as well as JSON when you want to publish bulk data. This makes sure users may use an array of tools, including off-the-shelf software, to import and analyse this data.
Publish bulk data on data.gov.uk and work out sure there is a prominent connect to it.
If your API serves personal or sensitive data, you have to log as soon as the data is provided and to whom. This can help you meet your requirements under General Data Protection Regulation (GDPR), react 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 bear in mind the possibility of denial-of-service attacks.
Open access does not always mean you are not able to throttle your API.
Consider the option of publishing data that are open data.gov.uk in place of via an API.When making use of open data do not use authentication in order to maximise the utilization of your API.