The following application that is web-based interface (API) standards guidance may help your organisation provide the best possible services to users.
API technical and data standards (v2 – 2019)
Publish your APIs over the internet by default. Email email@example.com if you believe your APIs should not be published over public infrastructure.
Proceed with the Technology Code of Practice
Make fully sure your APIs match the requirements of 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 to allow 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 national 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 use HTTP verbs with their specified purpose.
One of 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 construct a REST buy essay API, for example, if you are building an API to stream data.
You should use HTTPS when making 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 assistance 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 vendors that are low-cost offer TLS certificates. rather make certain potential API users can establish rely upon your certificates. Make certain you have a robust process for timely certificate renewal and revocation.
Your API may warrant linking important computer data together. You are able to your API more programmatically accessible by returning URIs, and by using existing standards and specifications.
Use Uniform Resource Identifiers (URIs) to identify certain data:
When your API returns data as a result to an HTTP call, you need to use URIs into the payload to spot certain data. Where appropriate, you should utilize specifications which use hypermedia, including CURIES, JSON-LD or HAL.
This will make it better to find those resources. For instance, you might return a “person” object which links to a resource representing their company within the way that is following
Your choice that is first for web APIs should be JSON where possible.
Only use another representation to create something in exceptional cases, like whenever you:
want to connect to a legacy system, for instance, one which only uses XML
will receive clear advantages from complying with a broadly adopted standard (for instance, SAML)
We advice you need to:
create responses as a JSON object and never an array (JSON objects can contain JSON arrays) – 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 ensure it is well described, and thus it is not treated as a array that is sequential
avoid unpredictable object keys such as those derived from 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 making use of the ISO 8601 standard to represent date and time 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, utilize the form 58:07Z that is 2017-08-09T13 .
The European Union mandates making use of the ETRS89 standard for the geographical scope of Europe. You may 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 can use other CRS coordinate systems for the rest of the 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 encoding text or 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 require.
When responding, your API must answer the request fully and specifically. As an example, an API should respond to the request “is this user married?” with a boolean. The clear answer should not return any longer detail than is necessary and may depend on your client application to correctly interpret it.
When designing your computer data fields, you should consider how the fields will meet user needs. Having a writer that is technical your team makes it possible to try this. You may also regularly examine your documentation.
For example, if you want to collect personal information in your dataset, before carefully deciding on your payload response, you may need to consider whether:
the design 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 far better to spell the field out up to now of birth
DOB makes sense when combined with DOD (date of death) or DOJ (date of joining)
It’s also wise to be sure you provide all the relevant options. For instance, the “marriage” field is likely to do have more than 2 states you wish to record: married , unmarried , divorced , widowed , estranged , annulled and so forth.
Depending on that which you decide, you may possibly select the following payload as a response:
When providing an Open Data API, you should let users download whole datasets unless they contain restricted information. Thus giving users:
the capability to analyse the dataset locally
support when performing a task requiring usage of your whole dataset (for instance, plotting a graph on school catchment areas in England)
Users must be able to index their copy that is local of utilizing their selection of database technology and then perform a query to satisfy their demands. This means future API downtime won’t affect them because 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 the consumer and for the API. Simply because:
rate limits would slow down access, or may even stop the whole dataset from downloading entirely
if the dataset is being updated at the same time with 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 example you might live stream your data or notify them that new information is available so that 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 permits them to keep their very own copy that is local to date and saves them having to re-download your whole dataset repeatedly.
There is certainlyn’t a recommended standard for this pattern, so users can try approaches that are different as:
encoding data in Atom/RSS feeds
using emergent patterns, such as for instance event streams used by products such as for instance Apache Kafka
making usage of open data registers
Make data for sale in CSV formats along with JSON when you need to write bulk data. This makes 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 while making sure there clearly was a prominent backlink to it.
In the event your API serves personal or sensitive data, you must log once the data is provided and to whom. This can help you satisfy your desires under General Data Protection Regulation (GDPR), respond 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 not able to throttle your API.
Look at the option of publishing open data on data.gov.uk as opposed to via an API.When making use of data that are open not use authentication to help you maximise the usage your API.