Use application-level authorisation should you want to control which applications can access your API, but not which end that is specific. It is suitable should you want to use rate limiting, auditing, or billing functionality. Application-level authorisation is probably not suited to APIs holding personal or data that are sensitive you probably trust your consumers, for example. another government department.
We advice using OAuth 2.0, the open authorisation framework (specifically with all the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, that can be used which will make API requests regarding the application’s own behalf.
To supply user-level authorisation
Use user-level authorisation should you want to control which end users can access your API. That is suited to working with personal or data that are sensitive.
For example, OAuth 2.0 is a authorisation that is popular in government, specifically with all the Authorisation Code grant type. Use OAuth 2.0 Scopes for more access control that is granular.
OpenID Connect (OIDC), which builds in addition to OAuth2, along with its use of JSON Web Token (JWT), might be suitable in some cases, for example a federated system.
For privacy and whitelisting
Use whitelisting if you’d like your API to be permanently or temporarily private, for instance to perform a beta that is private. You can whitelist per application or per user.
You ought not to whitelist the IP addresses of the APIs you consume. Simply because APIs can be provided using Content Delivery
Networks (CDNs) and scalable load balancers, which rely on flexible, rapid allocation of IP addresses and sharing. Rather than whitelisting, you should utilize an HTTPS egress proxy.
choose an appropriate refresh frequency and expiry period for the user access tokens – failure to refresh access tokens regularly can lead to vulnerabilities
allow your users to revoke authority
Invalidate an access token yourselves and force a reissue if there is a good reason to suspect a token has been compromised.
use time-based passwords that are one-timeTOTP) for extra security on APIs with application-level authorisation
use multi-factor authentication (MFA) and identity verification (IV) for additional security on APIs with user-level authorisation
ensure the tokens you provide have the narrowest permissions possible (narrowing the permissions means there’s a much lower risk to your API in the event that tokens are lost by users or compromised)
Your API security is just just like your day-to-day security processes.
Monitor APIs for unusual behaviour just like you’d closely monitor any website. Look for changes in IP addresses or users APIs that is using at times of your day. Browse the National Cyber Security Centre (NCSC) guidance to find out how exactly to implement a monitoring strategy plus the specifics of just how to monitor the security status of networks and systems.
All API naming in URLs (including the true name of the API, namespaces and resources) should:
use nouns in the place of verbs
be short, simple and clearly understandable
be human-guessable, avoiding technical or terms that are specialist possible
use hyphens instead of underscores as word separators for multiword names
As an example: api-name.api.gov.uk .
Generally, every one of your APIs needs to have its own domain, just as each service features its own domain. This may also avoid API sprawl and simplify your versioning.
Across them, such as common management, authentication and security approaches, you may need to consider if you provide multiple APIs and you have a business case that means you’ll deploy common services:
providing all of them from the same domain
differentiating them through the use of namespaces.
The function should be reflected by the namespace of government to be had by this API. Namespaces could be singular or plural, according to the situation.
Sub-resources must appear underneath the resource they relate genuinely to, but should go no more than three deep, for example: /resource/id/sub-resource/id/sub-sub-resource .
If it is actually a combination of multiple first or second level resources if you reach a third level of granularity (sub-sub-resource), you should review your resource construction to see.
You should use path parameters to identify a resource that is specific resources. As an example, /users/1 .
You really need to only allow query strings to be utilized in GET requests for filtering the values returned from an individual resource, for example /users?state=active or /users?page=2 .
You must never use query strings in GET requests for identification purposes, as an example, avoid using the query string /users? >.
Query strings should not be utilized for defining the behaviour of your API, for instance /users?action=getUser& >.
When iterating your API to add new or functionality that is improved you need to minimise disruption for the users so they usually do not incur unnecessary costs.
To minimise disruption for users, you need to:
make backwards compatible changes where possible – specify parsers ignore properties they don’t expect or understand to ensure changes are backwards compatible (this permits you to add fields to update functionality without requiring changes towards the client application)
make a endpoint that is new for significant changes
provide notices for deprecated endpoints
New endpoints do not always need certainly to accompany functionality that is new they still maintain backward compatibility
You should consider when you need to make a backwards incompatible change:
incrementing a version number when you look at the URL or even the HTTP header (start with /v1/ and increment with whole numbers)
supporting both old and new endpoints in parallel for a suitable time frame before discontinuing the old one
telling users of your API how exactly to validate data, for instance, tell them when a field is not going to be present for them to make certain their validation rules will treat that field as optional
Sometimes need that is you’ll make a bigger change and simplify a complex object structure by folding data from multiple objects together. In cases like this, make a object that is new at a new endpoint, as an example:
Combine data about users and accounts from:
/v1/users/123 and /v1/accounts/123
Set clear API deprecation policies so you’re not supporting old client applications forever.
State how long users have to upgrade, and buy essay just how you’ll notify them of the deadlines. For instance, at GDS, we usually contact developers directly but we also announce deprecation in HTTP responses using a ‘Warning’ header.
Your API consumers will want to test their application against your API before each goes live. Then you do not necessarily need to provide a test service if you have a read only API.
Supply them with a test service (sometimes known as a sandbox).
Should your API has complex or stateful behaviour, consider providing a test service that mimics the live service as much as possible, but bear in mind the price of achieving this.
In case your API requires authorisation, for example using OAuth 2.0, need that is you’ll include this in your test service or provide multiple quantities of a test service.
To assist you determine what to present, do user research – pose a question to your API consumers what a test that is sufficient would look like.
You ought to provide your development team aided by the ability to test thoroughly your API using sample test data, if applicable. Testing your API should not involve using production systems and production data.
A well-configured Content Delivery Network (CDN) may provide sufficient scalability for highly cacheable open data access APIs.
For APIs that don’t have those characteristics, you ought to set quota expectations for the users when it comes to capacity and rate available. Start small, relating to user needs, and react to requests to improve capacity by making sure your API can meet the quotas you have set.
Be sure users can examine your API that is full up the quotas you’ve got set.
Enforce the quotas you’ve got set, even if you have got excess capacity. This makes certain that your users can get a experience that is consistent you don’t have excess capacity, and certainly will design and build to deal with your API quota.
Just like user-facing services, you should test the capability of your APIs in a environment that is representative help to make sure it is possible to meet demand.
Where in fact the API delivers personal or information that is private, since the data controller, must provide sufficient timeouts on any cached information in your delivery network.