The following application that is web-based interface (API) standards guidance will help your organisation provide the most effective services to users.
API technical and data standards (v2 – 2019)
Publish your APIs on the internet by default. Email firstname.lastname@example.org if you believe your APIs ought not to be published over public infrastructure.
Proceed with the Technology Code of Practice
Make fully sure your APIs fulfill the requirements for the 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 so that they can maintain service level objectives and agreements when demand increases
are stable for them to maintain service level objectives and agreements when changed or dealing with unexpected events
Are reusable where possible so the national government does not duplicate work
Stick to the industry standard and where appropriate build APIs that are RESTful, designed to use HTTP verb requests to control data.
When handling requests, you need to 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 a few cases, it may 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.
There are multiple free and low-cost vendors that offer TLS certificates. rather Make sure API that is potential can establish rely upon 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
When your API returns data as a result to an HTTP call, you need to use URIs into the payload to determine certain data. Where appropriate, you should utilize specifications which use hypermedia, including CURIES, JSON-LD or HAL.
This makes it more straightforward to help me with my homework find those resources. For example, you could return a “person” object which links to a resource representing their company within the way that is following
Your first choice for all web APIs must be JSON where possible.
Only use another representation to construct something in exceptional cases, like whenever you:
have to connect to a legacy system, for instance, one which only uses XML
will receive clear advantages from complying with a broadly adopted standard (as an example, SAML)
We recommend you ought to:
create responses as a JSON object and not an array (JSON objects can contain JSON arrays) – arrays can limit the capacity to include metadata about results and limit the API’s capacity to add additional top-level keys as time goes by
document your JSON object to make sure it really is well described, and thus that it’s not treated as a sequential array
Avoid object that is unpredictable like those produced by data as this adds friction for clients
Use grammar that is consistent for object keys – choose under_score or CamelCase and start to become consistent
The government mandates with the ISO 8601 standard to represent time and date in your payload response. This helps people browse the 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 making use of the ETRS89 standard for the scope that is geographical of. You may want to use WGS 84 or any other CRS coordinate systems for European location data along with this.
Make use of the World Geodetic System 1984 (WGS 84) standard for the rest of the world. You are able to use other CRS coordinate systems for the rest of the world as well as this.
You need to 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 as opposed to ‘sending’ or ‘pushing’ data. This will make 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 must not return any longer detail than is necessary and should count on your client application to interpret it correctly.
When designing your data fields, you should look at the way the fields will meet user needs. Having a technical writer in your team makes it possible to do that. It is possible to regularly test thoroughly your documentation.
As an example, if you need to collect personal information in the dataset, before carefully deciding on your own payload response, you may have to consider whether:
the look can cope with names from cultures which don’t have first and names that are last
the abbreviation DOB makes sense or whether or not it’s better to spell out the field up to now of birth
DOB is reasonable when along with DOD (date of death) or DOJ (date of joining)
You should also make sure you provide all the relevant options. For instance, the “marriage” field will probably have more than 2 states you want to record: married , unmarried , divorced , widowed , estranged , annulled and so forth.
According to everything you decide, you may possibly pick the following payload as 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 ability to analyse the dataset locally
support when performing a task access that is requiring the whole dataset (as an example, plotting a graph on school catchment areas in England)
Users will be able to index their local copy of data utilizing their range of database technology and then perform a query to generally meet their needs. Which means that future API downtime won’t affect them because they already have got all the data they want.
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. It is because:
rate limits would slow down access, or may even stop the whole dataset from downloading entirely
in the event that dataset will be 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 an entire dataset, you should think about providing an easy method for them to keep writing to date. As an example you might live stream your 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 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 having 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 event streams employed by products such as for example Apache Kafka
making utilization of open data registers
Make data obtainable in CSV formats in addition to JSON when you wish to publish bulk data. This will make 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 make sure there clearly was a link that is prominent it.
In case your API serves personal or data that are sensitive you must log as soon as the data is provided and to whom. This can help you satisfy your desires under General Data Protection Regulation (GDPR), react to data subject access requests, 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 unable to throttle your API.
Think about the option of publishing data that are open data.gov.uk in place of via an API.When making use of data that are open not use authentication to help you maximise making use of your API.