API technical and data standards (v2 – 2019)
Publish your APIs on the internet by default. Email email@example.com if you believe your APIs must not be published over public infrastructure.
Stick to the Technology Code of Practice
Make sure your APIs satisfy the requirements associated with 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 to enable 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 and so the government does not duplicate work
Follow the industry standard and where build that is appropriate that are RESTful, which use HTTP verb requests to manipulate data.
When requests that are handling you should use HTTP verbs for their specified purpose.
One of many advantages of REST is you a framework for communicating error states that it gives.
In some cases, may possibly not be applicable to construct an escape API, for instance, when you are building an API to stream data.
You need to use HTTPS when designing 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. Usually do not use Sockets that is secure LayerSSL) or TLS v1.0.
You will find multiple free and vendors that are low-cost offer TLS certificates. rather make certain API that is potential can establish rely upon your certificates. Ensure 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 standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to spot data that are certain
If your API returns data in response to an HTTP call, you need to use URIs when you look at the payload to identify certain data. Where appropriate, you should use specifications that use hypermedia, including CURIES, JSON-LD or HAL.
This makes it easier to find those resources. As an example, you may return a “person” object which links to a resource representing their company when you look at the following way:
Your first choice for all web APIs should be JSON where possible.
Only use another representation to build something in exceptional cases, like whenever you:
need certainly to connect with a legacy system, for example, the one that only uses XML
will receive advantages that are clear complying with a broadly adopted standard (for instance, SAML)
We advice you should:
create responses as a JSON object and not an array (JSON objects can contain arrays that are JSON – arrays can limit the capability 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 it is not treated as a array that is sequential
avoid unpredictable object keys like those based on data since this adds friction for clients
use consistent grammar case for object keys – choose under_score or CamelCase and get consistent
The government mandates with the ISO 8601 standard to represent time and date in your payload response. It will help people see the right time correctly.
Use a consistent date format. For dates, this appears like 2017-08-09 . For dates and times, make use of the form 58:07Z that is 2017-08-09T13 .
The European Union mandates utilising the ETRS89 standard when it comes to scope that is geographical of. You may use WGS 84 or other CRS coordinate systems for European location data in addition to this.
Make use of the global world Geodetic System 1984 (WGS 84) standard for the rest of the world. You could use other CRS coordinate systems for the rest of the 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 react to ‘requests’ for data as opposed to ‘sending’ or ‘pushing’ data. This makes sure the API user only receives the information they might need.
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 clear answer should not return any more detail than is required and may depend on the customer application to correctly interpret it.
When designing your computer data fields, you should look at how the fields will meet user needs. Having a technical writer in your team will allow you to do that. You may regularly test thoroughly your documentation.
As an example, if you wish to collect private information in your dataset, before carefully deciding on your own 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 simpler to spell the field out up to now of birth
DOB is sensible when combined with DOD (date of death) or DOJ (date of joining)
You should also make certain you provide all the relevant options. For instance, the “marriage” field is likely to have more than 2 states you wish to record: married , unmarried , divorced , widowed , estranged , annulled and so on.
Depending on that which you decide, you may pick the payload that is following a response:
When providing an Open Data API, you really need to let users datasets that are download whole they contain restricted information. This provides users:
the capability to analyse the dataset locally
support when performing a job requiring usage of your whole dataset (for example, plotting a graph on school catchment areas in England)
Users will be able to index their copy that is local of utilizing their selection of database technology and then perform a query to generally meet their needs. Which means future API downtime won’t affect them because they already have got all the data they require.
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
in the event that dataset has been updated at the same time with the record-by-record download, users could get inconsistent records
In the event that you allow a user to download a whole dataset, you should consider providing a way for them to continue the good work to date. For instance you might live stream important computer data or notify them that new data is available so that API consumers know to download you API data periodically.
Don’t encourage users to help keep datasets that are large up to now by re-downloading them since 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 local copy up to date and saves them having to re-download the entire 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 event streams utilized by products such as for instance Apache Kafka
making usage of open data registers
Make data for sale in CSV formats as well as 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 and also make sure there clearly was a link that is prominent it.
If your API serves personal or data that are sensitive you have to log when the information 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) if you wish to give unfettered use of your API and you also do not need to 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 always buy essays online mean you are struggling to throttle your API.
Look at the option of publishing data that are open data.gov.uk in the place of via an API.when working with open data do not use authentication so you can maximise the use of your API.