API technical and data standards (v2 – 2019)
Publish your APIs over the internet by default. Email firstname.lastname@example.org if you think your APIs should not be published over public infrastructure.
Proceed with the Technology Code of Practice
Make sure your APIs fulfill the requirements associated with the Technology Code of Practice (TCoP) by simply making sure they:
stick to the Open Standards Principles of open access, consensus-based open process and licensing that is royalty-free
scale so 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 the national government will not duplicate work
Proceed with the industry standard and where appropriate build APIs that are RESTful, which use HTTP verb requests to manipulate data.
When requests that are handling you should utilize HTTP verbs because of their specified purpose.
One of many benefits of REST is you a framework for communicating error states that it gives.
In a few cases, may possibly not be applicable to build a REST API, for instance, when you’re building an API to stream data.
You need to 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 help with HTTPS.
Secure APIs Transport that is using Layer (TLS) v1.2. Do not use Sockets that is secure LayerSSL) or TLS v1.0.
You can find multiple free and low-cost vendors that offer TLS certificates. rather make certain potential API users can establish rely upon your certificates. Make certain you have a process that is robust timely certificate renewal and revocation.
Your API may warrant linking important computer data together. You possibly can make your API more programmatically accessible by returning URIs, and by using standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to spot data that are certain
If your API returns data as a result to an HTTP call, you should utilize URIs when you look at the payload to spot certain data. Where appropriate, you should use 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 in the way that is following
Your first option for all web APIs must be JSON where possible.
Only use another representation to construct something in exceptional cases, like when you:
need to connect to a legacy system, as an example, the one that only uses XML
will receive advantages that are clear complying with a broadly adopted standard (for instance, SAML)
We recommend you ought to:
create responses as a JSON object and never an array (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 by
document your JSON object to make sure it really is well described, and so that it is not treated as a array that is sequential
Avoid object that is unpredictable such as those produced from data since this adds friction for clients
Use grammar that is consistent for object keys – choose under_score or CamelCase and be consistent
The government mandates utilising the ISO 8601 standard to represent time and date in your payload response. This can help people browse the time correctly.
Use a date format that is consistent. 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 with the ETRS89 standard for the geographical scope of Europe. You could use WGS 84 or any other CRS coordinate systems for European location data in addition to this.
Make use of the World Geodetic System 1984 (WGS 84) standard for the rest of the world. You can even use other CRS coordinate essay writers systems for all of those other global world in addition to 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 text that is encoding other textual representations of data.
Configure APIs to react to ‘requests’ for data rather than ‘sending’ or ‘pushing’ data. This is why sure the API user only receives the given information they 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 solution should not return any longer detail than is required and should count on the client application to correctly interpret it.
When making your computer data fields, you should consider the way the fields will meet user needs. Having a technical writer in your team can help you try this. You can also regularly test your documentation.
For 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 it’s better to spell the field out to date of birth
DOB is sensible when along with DOD (date of death) or DOJ (date of joining)
You should also make sure you provide all of 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.
According to that which you decide, you may possibly select the payload that is following a response:
When providing an Open Data API, you ought to let users datasets that are download whole they contain restricted information. This provides users:
The ability to locally analyse the dataset
support when performing a task access that is requiring the complete dataset (for example, plotting a graph on school catchment areas in England)
Users must be able to index their copy that is local of using their selection of database technology and then perform a query to satisfy their needs. Which means that future API downtime won’t affect them since they already have all the data they want.
Using a record-by-record data API query to perform the action that is same be suboptimal, both for an individual and for the API. This is because:
rate limits would slow down access, or might even stop the dataset that is whole downloading entirely
in the event that dataset has been updated during the time that is same the record-by-record download, users could 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 can live stream your computer data or notify them that new data is available to ensure that 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 since this approach is wasteful and impractical. Instead, let users download incremental lists of changes to a dataset. This enables them to help keep their very own copy that is local to date and saves them having to re-download the whole dataset repeatedly.
There isn’t a recommended standard with 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 use of open data registers
Make data for sale in CSV formats in addition to JSON when you wish to publish bulk data. This makes sure users may use an array 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 is certainly a prominent url to it.
When your API serves personal or data that are sensitive you need to log when the information is provided and to whom. This will help you satisfy your desires under General Data Protection Regulation (GDPR), react 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 risk of denial-of-service attacks.
Open access does not always mean you will be unable to throttle your API.
Think about the option of publishing data that are open data.gov.uk instead of via an API.when working with data that are open not use authentication to help you maximise the employment of your API.