Use application-level authorisation if you want to control which applications can access your API, but not which specific end users. This is certainly suitable if you want to use rate limiting, auditing, or billing functionality. Application-level authorisation may not be ideal for APIs holding personal or sensitive data unless you probably trust your consumers, for instance. another government department.
We advice using OAuth 2.0, the open authorisation framework (specifically utilizing the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, which may be used to make API requests regarding the application’s own behalf.
To offer user-level authorisation
Use user-level authorisation should you want to control which end users can access your API. This can be ideal for working with personal or data that are sensitive.
For example, OAuth 2.0 is a authorisation that is popular in government, specifically aided by the Authorisation Code grant type. Use OAuth 2.0 Scopes for more access control that is granular.
OpenID Connect (OIDC), which builds together with OAuth2, using its utilization of JSON Web Token (JWT), might be suitable in many cases, for example a federated system.
For whitelisting and privacy
Use whitelisting if you like your API to be permanently or temporarily private, as an example to perform a beta that is private. You can whitelist per application or per user.
You should not whitelist the IP addresses associated with the APIs you consume. The reason being APIs could be provided using Content Delivery
Networks (CDNs) and load that is scalable, which rely on flexible, rapid allocation of IP addresses and sharing. Rather than whitelisting, an HTTPS should be used by you egress proxy.
choose an appropriate refresh frequency and expiry period for your user access tokens – failure to refresh access tokens regularly can cause vulnerabilities
let your users to revoke authority
invalidate an access token yourselves and force a reissue if there is a reason to suspect a token has been compromised.
use time-based passwords that are one-timeTOTP) for additional security on APIs with application-level authorisation
use multi-factor authentication (MFA) and identity verification (IV) for extra security on APIs with user-level authorisation
make sure 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. Try to find changes in IP addresses or users using APIs at unusual times during the the day. Read the National Cyber Security Centre (NCSC) guidance to find out just how to implement a monitoring strategy as well as the specifics of how to monitor the security status of networks and systems.
All API naming in URLs (like the name of your API, namespaces and resources) should:
use nouns as opposed to verbs
be short, simple and easy clearly understandable
be human-guessable, avoiding technical or terms that are specialist possible
use hyphens in the place of underscores as word separators for multiword names
As an example: api-name.api.gov.uk .
Generally, each of your APIs needs to have its own domain, just as each service possesses its own domain. This can 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 them all from the same domain
differentiating them with the use of namespaces.
The namespace should reflect the event of government being offered by this API. Namespaces could be singular or plural, depending on the situation.
Sub-resources must appear beneath the resource they connect with, but should go a maximum of 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 utilize path parameters to determine a specific resource or resources. As an example, /users/1 .
You need to only allow query strings to be utilized in GET requests for filtering the values returned from an resource that is individual for example /users?state=active or /users?page=2 .
You shouldn’t use query strings in GET requests for identification purposes, for example, avoid using the query string /users? >.
Query strings shouldn’t be utilized for defining the behaviour of your API, for example /users?action=getUser& >.
When iterating your API to include new or functionality that is improved you ought to minimise disruption for the users so that they usually do not incur unnecessary costs.
To minimise disruption for users, you ought to:
make backwards changes that are compatible possible – specify parsers ignore properties they don’t expect or understand to make certain changes are backwards compatible (this allows you to add fields to update functionality without requiring changes towards the client application)
make a new endpoint available for significant changes
provide notices for deprecated endpoints
New endpoints do not always need to accompany new functionality if they still maintain backward compatibility
If you want to make a backwards incompatible change you should consider:
incrementing a version number in the URL or even the HTTP header (focus on /v1/ and increment with whole numbers)
supporting both old and new endpoints in parallel for a time that is suitable before discontinuing the old one
telling users of your API how to validate data, as an example, tell them when a field isn’t going to be present to allow them to make certain their validation rules will treat that field as optional
Sometimes need that is paper writing service 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 new object available at a new endpoint, for instance:
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 how you’ll notify them of the deadlines. For example, 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. When you yourself have a read only API then you don’t necessarily need certainly to provide a test service.
Supply them with a test service (sometimes known as a sandbox).
In case your API has complex or stateful behaviour, consider providing a test service that mimics the live service whenever possible, but keep in mind the cost of carrying this out.
In the event the API requires authorisation, for instance using OAuth 2.0, need that is you’ll include this in your test service or provide multiple degrees of a test service.
To help you decide what to deliver, do user research – ask your API consumers what a sufficient test service would seem like.
You ought to provide your development team with all the ability to test thoroughly your API using sample test data, if applicable. Testing your API should not involve production that is using and production data.
For highly cacheable open data access APIs, a well-configured Content Delivery Network (CDN) might provide sufficient scalability.
For APIs that don’t have those characteristics, you need to set quota expectations for your users in terms of capacity and rate available. Start small, relating to user needs, and react to requests to increase capacity by simply making sure your API can meet up with the quotas you’ve got set.
Make certain users can test thoroughly your full API as much as the quotas you’ve got set.
Enforce the quotas you have set, even if you’ve got excess capacity. This will make certain that your users are certain to get a experience that is consistent you don’t have excess capacity, and certainly will design and build to take care of your API quota.
Just like user-facing services, you should test the capacity of your APIs in a environment that is representative help make sure you can meet demand.
Where in actuality the API delivers personal or information that is private, because the data controller, must definitely provide sufficient timeouts on any cached information in your delivery network.