API technical and data standards (v2 – 2019)
Publish your APIs on the internet by default. Email firstname.lastname@example.org 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 of the Technology Code of Practice (TCoP) by simply making sure they:
proceed with 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 so the national government does not duplicate work
Follow the industry standard and where build that is appropriate that are RESTful, designed to use HTTP verb requests to govern data.
When handling requests, you need to use HTTP verbs because of their specified purpose.
One of several 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, as an example, when you’re building an API to stream data.
You should utilize 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 guidance on HTTPS.
Secure APIs Transport that is using Layer (TLS) v1.2. Do not use Sockets that is secure LayerSSL) or TLS v1.0.
There are multiple free and low-cost vendors that offer TLS certificates. rather Make sure potential API users can establish trust in your certificates. Ensure you have a robust process for timely certificate renewal and revocation.
Your API may warrant linking your 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 spot data that are certain
If your API returns data in reaction to an call that is HTTP you need to use URIs into the payload to identify certain data. Where appropriate, you should use specifications that use hypermedia, including CURIES, JSON-LD or HAL.
This makes it much easier to find those resources. For instance, you could return a “person” object which links to a resource representing their company in the following way:
Your choice that is first for web APIs must be JSON where possible.
Only use another representation to build something in exceptional cases, like when you:
want to connect to a legacy system, as an example, the one that only uses XML
will get advantages that are clear complying with a broadly adopted standard (for instance, SAML)
We advice you really need to:
create responses as a JSON object rather than 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 sure it really is well described, and thus that 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 start to become consistent
The government mandates with the ISO 8601 standard to represent time and date in your payload response. This can help people browse the right time correctly.
Use a date format that is consistent. For dates, this seems like 2017-08-09 . For dates and times, make use of the form 58:07Z that is 2017-08-09T13 .
The European Union mandates with the ETRS89 standard for the scope that is geographical of. You can even use WGS 84 or any other CRS coordinate systems for European location data as well as this.
Utilize the global world Geodetic System 1984 (WGS 84) standard for all of those other world. You can use other CRS coordinate systems for all of those other world as well as this.
You should utilize 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 information.
Configure APIs to react to ‘requests’ for data as opposed to ‘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 answer should not return any more detail than is needed and really should rely on the customer application to interpret it correctly.
When making your data fields, you should consider how the fields will meet user needs. Having a writer that is technical your team will allow you to do this. You can even regularly test thoroughly your documentation.
For instance, if you want to collect private information in your dataset, before deciding on the payload response, you may have to consider whether:
the style can cope with names from cultures which pay someone to write my paper don’t have first and names that are last
the abbreviation DOB makes sense or whether it’s easier 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)
Its also wise to be sure you provide most of the options that are relevant. For example, the “marriage” field probably will have significantly more than 2 states you intend to record: married , unmarried , divorced , widowed , estranged , annulled an such like.
Depending on what you decide, you could select 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. Thus giving users:
the ability to analyse the dataset locally
support when performing a task requiring access to the complete dataset (for instance, plotting a graph on school catchment areas in England)
Users will be able to index their copy that is local of using their selection of database technology and then perform a query to satisfy their demands. This means 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 the consumer and for the API. The reason being:
rate limits would slow down access, or could even stop the whole dataset from downloading entirely
if the dataset has been updated at the time that is same 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. As an example you could live stream important computer data or notify them that new information is available making sure that API consumers know to download you API data periodically.
Don’t encourage users to help keep large datasets up 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 allows them to keep their very own local copy up to date and saves them needing to re-download your whole dataset repeatedly.
There clearly wasn’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 example event streams utilized by products such as for example Apache Kafka
making utilization of open data registers
Make data available in CSV formats in addition to JSON when you need to write bulk data. This will make sure users can use a wide range of tools, including off-the-shelf software, to import and analyse this data.
Publish bulk data on data.gov.uk while making sure there clearly was a prominent url to it.
In case your API serves personal or data that are sensitive you must log when the data is provided and to whom. This will help you satisfy your desires under General Data Protection Regulation (GDPR), respond to data access that is subject, and detect fraud or misuse.
Use open access (no control) if you want to give unfettered usage of your API and you don’t need to identify your users, as an example when providing open data . However, do bear in mind the possibility of denial-of-service attacks.
Open access does not always mean you may be unable to throttle your API.
Look at the option of publishing data that are open data.gov.uk instead of via an API.when utilizing data that are open not use authentication to help you maximise the usage of your API.