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 fully sure your APIs match the requirements regarding the Technology Code of Practice (TCoP) by making sure they:
follow the Open Standards Principles of open access, consensus-based open process and royalty-free licensing
scale so that they can 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 that the government does not duplicate work
Stick to the industry standard and where appropriate build APIs that are RESTful, designed to use HTTP verb requests to govern data.
When handling requests, you should utilize HTTP verbs because of their specified purpose.
One of many benefits of REST is that it gives you a framework for communicating error states.
In some cases, it may not be applicable to build a REST API, as an example, if you’re building an API to stream data.
You should utilize HTTPS when creating 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 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 sure you have a robust process for timely certificate renewal and revocation.
Your API may warrant linking your data together. You may make your API more programmatically accessible by returning URIs, and by using standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to recognize certain data:
If your API returns data in reaction to an call that is HTTP you need to use URIs in the payload to identify certain data. Where appropriate, you need to use specifications that use hypermedia, including CURIES, JSON-LD or HAL.
This will make it better to find those resources. As an example, you may return a “person” object which links to a resource representing their company in the way that is following
Your first option for all web APIs must be JSON where possible.
Only use another representation to create something in exceptional cases, like when you:
need to hook up to a legacy system, for instance, one that only uses XML
will receive clear advantages from complying with a broadly adopted standard (for example, SAML)
We advice you need to:
create responses as a JSON object rather than a wide range (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 certain it really is get college paper well described, and thus that it is not treated as a array that is sequential
Avoid object that is unpredictable like those based on 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 utilising the ISO 8601 standard to represent time and date in your payload response. This helps people see the right time correctly.
Use a consistent date format. For dates, this seems like 2017-08-09 . For dates and times, use the form 58:07Z that is 2017-08-09T13 .
The European Union mandates utilizing the ETRS89 standard for the scope that is geographical of. You can also use WGS 84 or other CRS coordinate systems for European location data along with this.
Utilize the global world Geodetic System 1984 (WGS 84) standard for the remainder world. You can even use other CRS coordinate systems for all of those other 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 for use in government when text that is encoding other textual representations of data.
Configure APIs to react to ‘requests’ for data rather than ‘sending’ or ‘pushing’ data. This will make sure the API user only receives the information they might need.
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 answer should not return any more detail than is needed and should count on your client application to correctly interpret it.
When designing important computer data fields, you should consider the way the fields will meet user needs. Having a writer that is technical your team makes it possible to do this. You can even regularly examine 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 cope with names from cultures which don’t have first and names that are last
the abbreviation DOB makes sense or whether it’s better to spell the field out up to now of birth
DOB is reasonable when coupled with DOD (date of death) or DOJ (date of joining)
It’s also advisable to be sure you provide all the options that are relevant. As an example, the “marriage” field will probably have more than 2 states you intend to record: married , unmarried , divorced , widowed , estranged , annulled an such like.
Based on what you decide, you may pick the following payload as a response:
When providing an Open Data API, you should 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 task requiring use of the 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 up their demands. Which 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 user and also for the API. The reason being:
rate limits would slow down access, or could even stop the whole dataset from downloading entirely
in the event that dataset is being updated during 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 means to allow them to keep writing to date. For instance you might live stream your data or notify them that new information is available in order for API consumers know to download you API data periodically.
Don’t encourage users to keep datasets that are large up to now 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 own 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 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 available in CSV formats along with JSON when you need to publish bulk data. This is why sure users can use an array of tools, including off-the-shelf software, to import and analyse this data.
Publish bulk data on data.gov.uk and also make sure there is a prominent backlink to it.
In case your API serves personal or sensitive data, you need to log as soon as the data is provided and to whom. This will help you meet your requirements 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 access to your API and you also need not identify your users, for instance when providing open data . However, do bear in mind the risk of denial-of-service attacks.
Open access does not mean you might be unable to throttle your API.
Look at the option of publishing open data on data.gov.uk instead of via an API.when working with data that are open not use authentication so you can maximise the usage your API.