API technical and data standards (v2 – 2019)
Publish your APIs over the internet by default. Email email@example.com if you believe your APIs should not be published over public infrastructure.
Stick to the Technology Code of Practice
Make fully sure your APIs match the requirements for the Technology Code of Practice (TCoP) by making sure they:
proceed with the Open Standards Principles of open access, consensus-based open process and royalty-free licensing
scale for 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 therefore the government does not duplicate work
Proceed with the industry standard and where appropriate build APIs that are RESTful, designed to use HTTP verb requests to control data.
When requests that are handling you need to use HTTP verbs with their specified purpose.
Among the advantages of REST is that it provides you with a framework for communicating error states.
In a few cases, may possibly not be applicable to construct a REST API, for instance, when you’re building an API to stream data.
You need to 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 using Transport Layer Security (TLS) v1.2. Do not use Sockets that is secure LayerSSL) or TLS v1.0.
You will find multiple free and low-cost vendors that offer TLS certificates. rather Make sure API that is potential can establish rely upon your certificates. Make sure you have a process that is robust timely certificate renewal and revocation.
Your API may warrant linking your data together. You could make your API more programmatically accessible by returning URIs, and also by using standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to determine data that are certain
As soon as your API returns data in response to an HTTP call, you should use URIs in the payload to spot certain data. Where appropriate, you should use specifications which use hypermedia, including CURIES, JSON-LD or HAL.
This makes it much easier to find those resources. For example, you might return a “person” object which links to a reference representing their company into the following way:
Your first choice for all web APIs must be JSON where possible.
Only use another representation to create something in exceptional cases, like when you:
want to connect to a legacy system, as an example, one which only uses XML
will receive advantages that are clear complying with a broadly adopted standard (as an example, SAML)
We advice you need to:
create essay writer responses as a JSON object and never a wide range (JSON objects can contain JSON arrays) – arrays can limit the capability to include metadata about results and limit the API’s capacity to add additional top-level keys in the future
document your JSON object to make sure it is well described, and so it is not treated as a array that is sequential
Avoid object that is unpredictable like those produced by 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 date and time in your payload response. It will help people browse the time correctly.
Use a date format that is consistent. For dates, this looks like 2017-08-09 . For dates and times, make use of the form 2017-08-09T13:58:07Z .
The European Union mandates utilizing the ETRS89 standard when it comes to geographical scope of Europe. You can use WGS 84 or other CRS coordinate systems for European location data in addition to this.
Use the global world Geodetic System 1984 (WGS 84) standard for the remainder world. It is possible to use other CRS coordinate systems for the remainder global world in addition to 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 data.
Configure APIs to react to ‘requests’ for data as opposed to ‘sending’ or ‘pushing’ data. This will make 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 clear answer should not return any longer detail than is necessary and may count on the customer application to interpret it correctly.
When designing important computer data fields, you should consider the way the fields will meet user needs. Having a technical writer in your team makes it possible to do this. You could regularly examine your documentation.
For example, you may need to consider whether if you need to collect personal information as part of your dataset, before deciding on your payload response:
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 more straightforward to spell out the field to date of birth
DOB is sensible when combined with DOD (date of death) or DOJ (date of joining)
Its also wise to make certain you provide most of the relevant options. For instance, the “marriage” field is likely to have significantly more than 2 states you wish to record: married , unmarried , divorced , widowed , estranged , annulled and so on.
Depending on what you decide, you could pick the following payload as a response:
When providing an Open Data API, you really need to let users datasets that are download whole they contain restricted information. This gives users:
the capability to analyse the dataset locally
support when performing an activity requiring usage of the whole dataset (as an example, plotting a graph on school catchment areas in England)
Users must be able to index their local copy of information using their selection of database technology and then perform a query to meet their needs. Which means 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 same action would be suboptimal, both for an individual and also for the API. It is because:
rate limits would slow down access, or might 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 could get inconsistent records
In the event that you allow a user to download a whole dataset, you should think about providing a means to allow them to keep it up to date. For instance you could live stream important computer data or notify them that new information is available in order that 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 because this approach is wasteful and impractical. Instead, let users download incremental lists of changes to a dataset. This allows them to help keep their particular local copy up to date and saves them being forced to re-download the whole dataset repeatedly.
There 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 utilized by products such as for instance Apache Kafka
making utilization of open data registers
Make data obtainable in CSV formats along with JSON when you need to publish bulk data. This makes sure users may use a wide range of tools, including off-the-shelf software, to import and analyse this data.
Publish bulk data on data.gov.uk and also make sure there is certainly a link that is prominent it.
In case your API serves personal or sensitive data, you have to log when the data is provided and to whom. This will help you satisfy your desires under General Data Protection Regulation (GDPR), respond to data subject access requests, and detect fraud or misuse.
Use open access (no control) should you want to give unfettered use of your API and you don’t need to identify your users, as an example when providing open data . However, do bear in mind the possibility of denial-of-service attacks.
Open access does not always mean you are unable to throttle your API.
Look at the option of publishing data that are open data.gov.uk in place of via an API.when working with data that are open not use authentication so you can maximise the use of your API.