API technical and data standards (v2 – 2019)
Publish your APIs over the internet by default. Email firstname.lastname@example.org if you believe your APIs ought not to be published over public infrastructure.
Follow the Technology Code of Practice
Make fully sure your APIs fulfill the requirements of this Technology Code of Practice (TCoP) by simply making sure they:
follow the Open Standards Principles of open access, consensus-based open process and royalty-free licensing
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 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 control data.
When handling requests, you should utilize HTTP verbs for their specified purpose.
One of several benefits of REST is you a framework for communicating error states that it gives.
In a few cases, it may not be applicable to create a REST API, for instance, if you are building an API to stream data.
You should use HTTPS when designing APIs.
Adding HTTPS will secure connections to your API, preserve user privacy, ensure data integrity, and authenticate the server supplying the API. The Service Manual provides more guidance on HTTPS.
Secure APIs Transport that is using Layer (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 certain potential API users can establish trust in your certificates. Make certain you have a robust process for timely certificate renewal and revocation.
Your API may warrant linking your computer data together. You possibly can make your API more programmatically accessible by returning URIs, and by using standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to identify data that are certain
If your API returns data in reaction to an HTTP call, you should utilize URIs in the payload to recognize certain data. Where appropriate, you should utilize specifications that use hypermedia, including CURIES, JSON-LD or HAL.
This will make it simpler to find those resources. As an example, you could return a “person” object which links to a resource representing their company in the way that is following
Your first option for all web APIs should be JSON where possible.
Only use another representation to build something in exceptional cases, like once you:
want to connect with a legacy system, for instance, the one that only uses XML
will receive advantages that are clear complying with a broadly adopted standard (for example, SAML)
We advice you need to:
create responses as a JSON object and not a wide range (JSON objects can contain JSON arrays) – arrays can limit the capability to include metadata about results and limit the API’s capability 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’s not treated as a array that is sequential
avoid unpredictable object keys such as 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. It will help people read the right time correctly.
Use a consistent date format. For dates, this appears like 2017-08-09 . For dates and times, utilize the form 58:07Z that is 2017-08-09T13 .
The European Union mandates using the ETRS89 standard when it comes to geographical scope of Europe. You may use WGS 84 or any other CRS coordinate systems for European location data as well as this.
Make use of the global world Geodetic System 1984 (WGS 84) standard for all of those other world. You can use other CRS coordinate systems for all of those other world as well as this.
You should utilize GeoJSON for the exchange of location information.
The Unicode Transformation Format (UTF-8) standard is mandatory for usage in government when text that is encoding other textual representations of data.
Configure APIs to react to ‘requests’ for data rather than ‘sending’ or ‘pushing’ data. This is why sure the API user only receives the given information they might need.
When responding, your API must answer the request fully and specifically. For instance, an API should respond to the request “is this essay helper user married?” with a boolean. The solution must not return any more detail than is necessary and should rely on the client application to interpret it correctly.
When designing your computer data fields, you should consider the way the fields will meet user needs. Having a writer that is technical your team will allow you to do this. You may also regularly test thoroughly your documentation.
As an example, if you want to collect information that is personal as part of 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 or not it’s safer to spell the field out to date of birth
DOB makes sense when combined with DOD (date of death) or DOJ (date of joining)
Its also wise to be sure you provide all of the relevant options. For instance, the “marriage” field is likely to have significantly more than 2 states you want to record: married , unmarried , divorced , widowed , estranged , annulled and so on.
According to what you decide, you could choose the payload that is following a response:
When providing an Open Data API, you should let users download whole datasets unless they contain restricted information. This provides users:
The ability to locally analyse the dataset
support when performing an activity requiring use of the entire dataset (as an example, plotting a graph on school catchment areas in England)
Users should be able to index their local copy of data using their range of database technology and then perform a query to meet up their needs. Which 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 same action would be suboptimal, both for the user and also for the API. The reason being:
rate limits would slow down access, or may even stop the whole dataset from downloading entirely
in the event that dataset will be updated during the time that is same the record-by-record download, users may get inconsistent records
Up to date if you allow a user to download an entire dataset, you should consider providing a way for them to keep it. For instance you might live stream important computer data or notify them that new information is available making sure that API consumers know to download you API data periodically.
Don’t encourage users to 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 enables them to keep their very own local copy up to date and saves them being forced to re-download the entire 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 employed by products such as for instance Apache Kafka
making use of open data registers
Make data available in CSV formats in addition to JSON when you need to write bulk data. This will make sure users can 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 then make sure there clearly was a prominent link to it.
In the event your API serves personal or sensitive data, you must log when the data is provided and to whom. This will help you work for you under General Data Protection Regulation (GDPR), react to data access that is subject, and detect fraud or misuse.
Use open access (no control) if you would like give unfettered access to your API and also you do not need to identify your users, for instance when providing open data . However, do keep 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 open data on data.gov.uk in the place of via an API.When using open data do not use authentication to help you maximise the usage of your API.