Use application-level authorisation if you wish to control which applications can access your API, but not which specific end users. This might be suitable if you’d like to use rate limiting, auditing, or billing functionality. Application-level authorisation may not be suited to APIs holding personal or sensitive data unless you really trust your consumers, for instance. another government department.
We advice using OAuth 2.0, the open authorisation framework (specifically aided by the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, and that can be used to make API requests in the application’s own behalf.
To produce user-level authorisation
Use user-level authorisation if you want to control which end users can access your API. This can be suited to working with personal or data that are sensitive.
For example, OAuth 2.0 is a authorisation that is popular in government, specifically utilizing the Authorisation Code grant type. Use OAuth 2.0 Scopes for more granular access control.
OpenID Connect (OIDC), which builds in addition to OAuth2, along with its utilization of JSON Web Token (JWT), might be suitable in some instances, for example a federated system.
For privacy and whitelisting
Use whitelisting if you prefer your API to be permanently or temporarily private, for example to operate a beta that is private. You can whitelist per application or per user.
You ought not to whitelist the IP addresses associated with APIs you consume. It is because APIs may 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 use an HTTPS egress proxy.
choose a suitable frequency that is refresh expiry period for the user access tokens – failure to refresh access tokens regularly can result in 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 one-time passwords (TOTP) 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 far lower risk to your API in the event that tokens are lost by users or compromised)
Your API security is only just like your day-to-day security processes.
Monitor APIs for unusual behaviour just like you’d closely monitor any website. Look for alterations in IP addresses or users using APIs at unusual times of a single day. See the National Cyber Security Centre (NCSC) guidance to find out just how to implement a monitoring strategy additionally the specifics of just how to monitor the security status of networks and systems.
All API naming in URLs (including the name of your API, namespaces and resources) should:
use nouns in the place of verbs
be short, simple and clearly understandable
be human-guessable, avoiding technical or specialist terms where possible
use hyphens rather than underscores as word separators for multiword names
For instance: api-name.api.gov.uk .
Generally, every one of your APIs should have its domain that is own as each service possesses its own domain. This can also avoid API sprawl and simplify your versioning.
In the event that you provide multiple APIs and you also have a business case which means you’ll deploy common services across them, such as for example common management, authentication and security approaches, you may need to consider:
providing them all through the domain that is same
differentiating them by using namespaces.
The function should be reflected by the namespace of government to be had by this API. Namespaces may be singular or plural, with regards to the situation.
Sub-resources must write my paper appear beneath the resource they relate genuinely to, but is going no more than three deep, as an 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 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 really should not be useful for defining the behaviour of one’s API, for example /users?action=getUser& >.
When iterating your API to include new or functionality that is improved you should minimise disruption for your 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 make certain changes are backwards compatible (this allows you to definitely add fields to update functionality without requiring changes to your client application)
make a new endpoint available for significant changes
provide notices for deprecated endpoints
New endpoints usually do not always need to accompany new functionality if they still maintain backward compatibility
You should consider when you need to make a backwards incompatible change:
incrementing a version number into the URL or the HTTP header (start with /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 exactly to validate data, as an example, tell them when a field will not be there to enable them to make sure their validation rules will treat that field as optional
Sometimes you’ll need to make a more substantial 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, 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 users that are long to upgrade, and 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 they go live. Then you do not necessarily need to provide a test service if you have a read only API.
Provide them with a test service (sometimes described as a sandbox).
The cost of doing this if 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.
If 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 help you decide what to present, do user research – ask your API consumers what a sufficient test service would appear to be.
You need to provide your development team utilizing the ability to test your API using sample test data, if applicable. Testing your API should not involve using production systems and production data.
For highly cacheable open data access APIs, a well-configured Content Delivery Network (CDN) may provide sufficient scalability.
For APIs that don’t have those characteristics, you need to set quota expectations for the users in terms of capacity and rate available. Start small, according to user needs, and react to requests to increase capacity by making sure your API can meet the quotas you’ve got set.
Make certain users can test thoroughly your API that is full up the quotas you have set.
Enforce the quotas you have got set, even when you have got excess capacity. This makes sure that your users can get a consistent experience when you don’t have excess capacity, and can design and build to address your API quota.
Much like user-facing services, you ought to test the ability of your APIs in a representative environment to help make sure you can meet demand.
Where in fact the API delivers personal or personal information you, whilst the data controller, must provide sufficient timeouts on any cached information in your delivery network.