Listed here 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 api-standards-request@digital.cabinet-office.gov.uk if you believe your APIs ought not to be published over public infrastructure.

Stick to the Technology Code of Practice

Make fully sure your APIs satisfy the requirements regarding the Technology Code of Practice (TCoP) by making sure they:

stick to the Open Standards Principles of open access, consensus-based open process and royalty-free licensing

scale so 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 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 handling requests, you should use HTTP verbs with their specified purpose.

One of many advantages of REST is you a framework for communicating error states that it gives.

In a few full 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 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 guidance on HTTPS.

Secure APIs using Transport Layer Security (TLS) v1.2. Do not use Secure Sockets Layer (SSL) or TLS v1.0.

There are multiple free and vendors that are low-cost offer TLS certificates. rather make certain 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 computer data together. You can 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 in response to an HTTP call, you should use URIs when you look at the payload to recognize certain data. Where appropriate, you should use 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 into the following way:

Your first option for all web APIs must be JSON where possible.

Only use another representation to create something in exceptional cases, like when you:

need to connect to a legacy system, for instance, one that only uses XML

will get clear advantages from complying with a broadly adopted standard (for example, SAML)

We advice you ought to:

create responses as a JSON object and never an array (JSON objects can contain arrays that are JSON – 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 certain it is well described, and so that it’s not treated as a array that is sequential

Avoid object that is unpredictable like those derived from data as this adds friction for clients

use consistent grammar case for object keys – choose under_score or CamelCase and get consistent

The government mandates utilising the ISO 8601 standard to represent time and date in your payload response. It will help people browse the time correctly.

Use a date format that is consistent. For dates, this appears like 2017-08-09 . For dates and times, use the form 2017-08-09T13:58:07Z .

The European Union mandates making use of the ETRS89 standard when it comes to geographical scope of Europe. You’ll be able to use WGS 84 or any other CRS coordinate systems for European location data along with this.

Utilize the World Geodetic System 1984 (WGS 84) standard for the rest of the world. You may use other CRS coordinate systems for all of those other world along with 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 data.

Configure APIs to react to ‘requests’ for data as opposed to ‘sending’ or ‘pushing’ data. This makes sure the API user only receives the information they might require.

When responding, your API must answer the request fully writing essays for students and specifically. For example, an API should respond to the request “is this user married?” with a boolean. The solution should not return any more detail than is necessary and really should depend on the customer application to interpret it correctly.

When making your computer data fields, you should think about how the fields will meet user needs. Having a writer that is technical your team makes it possible to try this. It is possible to regularly test your documentation.

As an 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 design 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 simpler to spell the field out up to now of birth

DOB is reasonable when combined with DOD (date of death) or DOJ (date of joining)

It’s also advisable to make sure you provide all of the options that are relevant. For example, the “marriage” field probably will do have more than 2 states you wish to record: married , unmarried , divorced , widowed , estranged , annulled and so forth.

Based on what you decide, you may possibly choose the payload that is following a response:

When providing an Open Data API, you should let users datasets that are download whole they contain restricted information. This gives users:

the ability to analyse the dataset locally

support when performing a task access that is requiring your whole dataset (for instance, plotting a graph on school catchment areas in England)

Users will be able to index their local copy of information employing their selection of database technology and then perform a query to fulfill 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 action that is same be suboptimal, both for an individual 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 during the same time with the record-by-record download, users could 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 can live stream your data or notify them that new data is available to ensure 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 because this approach is wasteful and impractical. Instead, let users download incremental lists of changes to a dataset. This permits them to help keep their very own copy that is local 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 different approaches such as:

encoding data in Atom/RSS feeds

using emergent patterns, such as for instance event streams used by products such as for example Apache Kafka

making usage of open data registers

Make data available in CSV formats as well as JSON when you want to publish bulk data. This is why 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 make sure there was a prominent connect to it.

If your API serves personal or sensitive data, you must log once the data is provided and to whom. This will help you satisfy your desires 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’d like to give unfettered use of your API and you also need not identify your users, as an example when providing open data . However, do bear in mind the risk of denial-of-service attacks.

Open access doesn’t mean you might be struggling to throttle your API.

Look at the option of publishing open data on 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.