The next application that is web-based interface (API) standards guidance will help your organisation deliver the best possible services to users.

API technical and data standards (v2 – 2019)

Publish your APIs on the internet by default. Email if you were to think your APIs ought not to be published over public infrastructure.

Proceed with the Technology Code of Practice

Make sure your APIs match the requirements regarding the 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 they can maintain service level objectives and agreements when demand increases

are stable so they can maintain service level objectives and agreements when changed or dealing with unexpected events

Are reusable where possible so the national government will not duplicate work

Stick to the industry standard and where build that is appropriate that are RESTful, which use HTTP verb requests to manipulate data.

When handling requests, you should use HTTP verbs with their specified purpose.

Among the benefits of REST is you a framework for communicating error states that it gives.

In a few cases, may possibly not be applicable to construct an escape API, for instance, whenever you are 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 company 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 trust in your certificates. Be sure you have a process that is robust 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 also by using standards that are existing specifications.

Use Uniform Resource Identifiers (URIs) to determine data that are certain

When your API returns data in reaction to an HTTP call, you should use URIs into the payload to determine certain data. Where appropriate, you should use specifications that use hypermedia, including CURIES, JSON-LD or HAL.

This will make it better to find those resources. For example, you could 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:

have to hook up to a legacy system, for instance, the one that only uses XML

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

We advice you should:

create responses as a JSON object and never an array (JSON objects can contain arrays that are JSON – arrays can limit the ability to include metadata about results and limit the API’s ability to add additional top-level keys as time goes by

document your JSON object to make certain it really is well described, and so it is not treated as a sequential array

avoid unpredictable object keys like those derived from data since this adds friction for clients

Use grammar that is consistent for object keys – choose under_score or CamelCase and get consistent

The government mandates making use of the ISO 8601 standard to represent time and date in your payload response. This helps 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 for the scope that is geographical of. You could use WGS 84 or other CRS coordinate systems for European location data as well as this.

Utilize the World Geodetic System 1984 (WGS 84) standard for the remainder world. You’ll be able to use other CRS coordinate systems for the rest of the global world as well as this.

You should use GeoJSON for the exchange of location information.

The Unicode Transformation Format (UTF-8) standard is mandatory to be used in government when text that is encoding other textual representations of information.

Configure APIs to react to ‘requests’ for data rather than ‘sending’ or ‘pushing’ data. This will make sure the API user only receives the given information they might require.

When responding, your API must answer the request fully and specifically. For instance, an API should react to the request “is this user married?” with a boolean. The clear answer should not return any more detail than is required and may count on your client application to correctly interpret it.

When designing important computer data fields, you should think about how the fields will meet user needs. Having a writer that is technical your team can help you try this. You may also regularly test thoroughly 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 design can deal with names from cultures which don’t have first and last names

the abbreviation DOB makes sense or whether or not it’s far better to spell out the field up to now of birth

DOB is sensible when coupled with DOD (date of death) or DOJ (date of joining)

You should also make sure you provide most of the relevant options. For example, the “marriage” field is likely to have more than 2 states you wish to record: married , unmarried , divorced , widowed , estranged , annulled an such like.

Depending on that which you decide, you might pick the following payload as a response:

When providing an Open Data API, you really need to let users download whole datasets unless they contain restricted information. This provides users:

The ability to locally analyse the dataset

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

Users should be able to index their local copy of data utilizing their choice of database technology and then perform a query to meet their needs. This means future API downtime won’t affect them since they already have all the info they need.

Using a record-by-record data API query to perform the same action would be suboptimal, both for an individual and for the API. The reason being:

rate limits would slow down access, or might even stop the dataset that is whole downloading entirely

if the dataset will be updated during the time that is same 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. As an example you can live stream your 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 help keep large datasets up up to now by re-downloading them as this approach is wasteful and impractical. Instead, let users download incremental lists of changes to a dataset. This permits them to keep their particular copy that is local to date and saves them being forced to re-download your whole dataset repeatedly.

There is certainlyn’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 Apache Kafka

making usage of open data registers

Make data for sale in CSV formats as well as JSON when you wish to write bulk data. This makes sure users can use an array of tools, including software that is off-the-shelf to import and analyse this data.

Publish bulk data on and also make sure there clearly was a prominent backlink to it.

When your API serves personal or data that are sensitive you need to log as soon as the information is provided and to whom. This can help you meet your requirements 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 risk of denial-of-service attacks.

Open access does not always mean you will be unable to throttle your API.

Consider the option of publishing data that are open as opposed to via an API.when utilizing data that are open not use authentication in order to maximise the use of your API.