The following web-based application programming interface (API) standards guidance will help your organisation provide the best possible 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.

Follow the Technology Code of Practice

Make fully sure your APIs match the requirements for the Technology Code of Practice (TCoP) by simply making sure they:

stick to the Open Standards Principles of open access, consensus-based write my paper for me open process and royalty-free licensing

scale for them to 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 government does not duplicate work

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

When handling requests, you should utilize HTTP verbs for his or her specified purpose.

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

In a few cases, it may not be applicable to create a REST API, for example, if 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 supplying the API. The Service Manual provides more help with HTTPS.

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

You can find multiple free and vendors that are low-cost offer TLS certificates. rather Make sure API that is potential 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 could make your API more programmatically accessible by returning URIs, and also by using existing standards and specifications.

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

As soon as your API returns data as a result to an call that is HTTP you should use URIs when you look at the payload to recognize certain data. Where appropriate, you should use specifications which use hypermedia, including CURIES, JSON-LD or HAL.

This will make it more straightforward to find those resources. For instance, you could return a “person” object which links to a reference representing their company in the following way:

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 example, the one that 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 a wide range (JSON objects can contain arrays that are JSON – arrays can limit the ability to include metadata about results and limit the API’s capability to add additional top-level keys as time goes on

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 such as those based on data since this adds friction for clients

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

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

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

The European Union mandates using the ETRS89 standard for the geographical scope of Europe. You can use WGS 84 or 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 the remainder world. You’ll be able to use other CRS coordinate systems for the remainder global world along with this.

You should utilize GeoJSON for the exchange of location information.

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

Configure APIs to respond to ‘requests’ for data rather than ‘sending’ or ‘pushing’ data. This is why sure the API user only receives the information they require.

When responding, your API must answer the request fully and specifically. For example, an API should respond to the request “is this user married?” with a boolean. The answer must not return any longer detail than is required and may rely on the customer application to interpret it correctly.

When designing important computer data fields, you should look at the way the fields will meet user needs. Having a writer that is technical your team will allow you to repeat this. You may want to regularly test thoroughly 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 look can deal 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 far better to spell the field out to date of birth

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

You should also make sure you provide all the relevant options. As an example, the “marriage” field probably will do have more than 2 states you want to record: married , unmarried , divorced , widowed , estranged , annulled and so forth.

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

When providing an Open Data API, you ought to let users datasets that are download whole they contain restricted information. Thus giving users:

The ability to locally analyse the dataset

support when performing a job 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 copy that is local of using their selection of database technology and then perform a query to generally meet their demands. Which means that future API downtime won’t affect them since they already have all the info they require.

Using a record-by-record data API query to perform the action that is same be suboptimal, both for the user and for the API. Simply because:

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

in the event that dataset is being updated during the time that is same the record-by-record download, users could get inconsistent records

In the event that you allow a user to download a complete dataset, you should think about providing a way to allow them to continue the good work to date. As an example you can live stream your computer data or notify them that new information 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 because this approach is wasteful and impractical. Instead, let users download incremental lists of changes to a dataset. This enables them to help keep their particular copy that is local to date and saves them needing to re-download your whole dataset repeatedly.

There isn’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 instance Apache Kafka

making usage of open data registers

Make data available in CSV formats in addition to JSON when you need to publish bulk data. This is why sure users can use a wide range 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 was a link that is prominent it.

In case your API serves personal or data that are sensitive you must log when the information is provided and to whom. This will 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) if you would like give unfettered use of your API and you also need not identify your users, for example when providing open data . However, do bear in mind the possibility of denial-of-service attacks.

Open access does not mean you may be struggling to throttle your API.

Look at the option of publishing data that are open data.gov.uk instead of via an API.When using open data do not use authentication to help you maximise the application of your API.

Leave a Reply