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.
Follow the Technology Code of Practice
Make fully sure your APIs fulfill 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 licensing that is royalty-free
scale to enable them to maintain service level objectives and agreements when demand increases
are stable for them to maintain service level objectives and agreements when changed or dealing 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 govern data.
When handling requests, you should use HTTP verbs for his or her specified purpose.
Among the benefits of REST is you a framework for communicating error states that it gives.
In certain cases, it may not be applicable to build an escape API, for instance, if you’re building an API to stream data.
You should utilize 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 guidance on HTTPS.
Secure APIs Transport that is using Layer (TLS) v1.2. Usually 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 rely upon your certificates. Make certain you have a robust process for timely certificate renewal and revocation.
Your API may warrant linking your data together. You could make your API more programmatically accessible by returning URIs, and by using standards that are existing specifications.
Use Uniform Resource Identifiers (URIs) to recognize data that are certain
If your API returns data as a result 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 will make it more straightforward to find those resources. As an example, you might return a “person” object which links to a reference representing their company within the following way:
Your choice that is first for web APIs must be JSON where possible.
Only use another representation to construct something in exceptional cases, like once you:
need certainly to connect to a legacy system, for instance, one that only uses XML
will receive clear advantages from complying with a broadly adopted standard (for instance, SAML)
We advice you really need to:
create responses as a JSON object and not an array (JSON objects can contain JSON arrays) – arrays can limit the capacity to include metadata about results and limit the API’s capacity to add additional top-level keys in the future
document your JSON object to ensure it is well described, and so 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 start to become consistent
The government mandates with the ISO 8601 standard to represent time and date in your payload response. This helps people browse 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 utilizing the ETRS89 standard for the scope that is geographical of. You can use WGS 84 or any other CRS coordinate systems for European location data as well as this.
Utilize the World Geodetic System 1984 (WGS 84) standard for all of those other world. You are able to use other CRS coordinate systems for the remainder 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 for usage in government when encoding text or other textual representations of information.
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 might need.
When responding, your API must answer the request fully and specifically. For example, an API should react to the request “is this user married?” with a boolean. The clear answer should not return any more detail than is necessary and really should rely on the customer application to correctly interpret it.
When making your computer data fields, you should think about the way the fields will meet user needs. Having a technical writer in your team will allow you to try this. You could regularly test 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 style can deal with names from cultures which don’t have first and last names
the abbreviation DOB makes sense or whether it’s safer to spell the field out to date of birth
DOB is practical when coupled with DOD (date of death) or DOJ (date of joining)
Its also wise to make sure you provide all the options that are relevant. For instance, the “marriage” field is likely to do have more than 2 states you intend to record: married , unmarried , divorced , widowed , estranged , annulled an such like.
According to everything you decide, you may possibly choose the following payload as a response:
When providing an Open Data API, you need to let users download whole datasets unless 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 (as an example, plotting a graph on school catchment areas in England)
Users will be able to index their local copy of information using their range of database technology and then perform a query to generally meet their demands. This means that future API downtime won’t affect them because they already have got all the info they need.
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. This is because:
rate limits would slow down access, or could even stop the dataset that is whole downloading entirely
if the dataset is being updated at 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 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 help keep large datasets up to date 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 keep their very own copy that is local to date and saves them having to re-download the entire dataset repeatedly.
There isn’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 Apache Kafka
making utilization of open data registers
Make data available in CSV formats along with JSON when you need to write 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 edubirdies.org/buy-essay-online company.gov.uk and then make sure there is certainly a prominent backlink to it.
When your API serves personal or data that are sensitive you have to log if the information is provided and to whom. This can help you meet your requirements under General Data Protection Regulation (GDPR), react to data access that is subject, 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 keep in mind the possibility of denial-of-service attacks.
Open access does not always mean you might be unable to throttle your API.
Look at the option of publishing open data on data.gov.uk rather than via an API.when utilizing data that are open not use authentication in order to maximise the application of your API.