Use application-level authorisation if you wish to control which applications can access your API, but not which end that is specific. It is suitable if you wish to use rate limiting, auditing, or billing functionality. Application-level authorisation is typically not suited to APIs holding personal or sensitive data unless you actually trust your consumers, for example. another government department.

We recommend 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, that could be used in order to make API requests on the application’s behalf that is own.

To provide authorisation that is user-level

Use user-level authorisation if you wish to control which end users can access your API. This is ideal for dealing with personal or sensitive data.

For example, OAuth 2.0 is a popular authorisation method in government, specifically using the Authorisation Code grant type. Use OAuth 2.0 Scopes for more granular access control.

OpenID Connect (OIDC), which builds along with OAuth2, having its utilization of JSON Web Token (JWT), may be suitable in some cases, as an example a system that is federated.

For privacy and whitelisting

Use whitelisting if you would like your API to be permanently or temporarily private, for instance 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 might be provided Content that is using Delivery

Networks (CDNs) and load that is scalable, which depend on flexible, rapid allocation of IP addresses and sharing. Instead of whitelisting, you need to 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 when 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

ensure the tokens you provide have the narrowest permissions possible (narrowing the permissions means there’s a far lower risk to your API if the tokens are lost by users or compromised)

Your API security is only as good as your day-to-day security processes.

Monitor APIs for unusual behaviour exactly like you’d closely monitor any website. Search for alterations in IP addresses or users using APIs at unusual times of a single day. Browse the National Cyber Security Centre (NCSC) guidance to discover simple tips to implement a monitoring strategy and the specifics of how to monitor the security status of networks and systems.

All API naming in URLs (such as the name of the API, namespaces and resources) should:

use nouns rather than 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

As an example: api-name.api.gov.uk .

Generally, all of your APIs must 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 through the same domain

differentiating them by using namespaces.

The function should be reflected by the namespace of government being offered by this API. Namespaces could be singular or plural, according to the situation.

Sub-resources must appear underneath the resource they connect with, but is going 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 need to use path parameters to identify a resource that is specific resources. As an example, /users/1 .

You ought 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 should never use query strings in GET requests for identification purposes, as an example, avoid using the query string /users? >.

Query strings should not be used for defining the behaviour of one’s API, for example /users?action=getUser& >.

When iterating your API to add new or improved functionality, you should minimise disruption for the users so that 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 permits one to add fields to update functionality without requiring changes into the client application)

make a new endpoint available 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 time that is suitable before discontinuing the old one

telling users of your API how exactly to validate data, for example, inform them when a field isn’t going to be there for them to make sure their validation rules will treat that field as optional

Sometimes need that is you’ll make a larger change and simplify a complex object structure by folding data from multiple objects together. In this case, make a new object available at a new endpoint, for 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 client that is old forever.

State how long users have to upgrade, and just how you’ll notify them of these 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. Then you do not necessarily need to provide a test service if you have a read only API.

Give them a test service (sometimes described as a sandbox).

When your API has complex or stateful behaviour, consider providing a test service that mimics the live service as much as possible, but keep in mind the cost of carrying this out.

If your API requires authorisation, for example using OAuth 2.0, you’ll need to include this in your test service or provide multiple degrees of a test service.

To help you decide what to supply, do user research – ask your API consumers what a test that is sufficient would appear to be.

You should provide your development team with the ability to test your API using do my homework sample test data, if applicable. Testing your API should not involve production that is using 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 really need to set quota expectations for your users when it comes to capacity and rate available. Start small, based on user needs, and respond 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 examine your API that is full up the quotas you have got set.

Enforce the quotas you have got set, even when you’ve got excess capacity. This is why certain that your users will get a consistent experience when you don’t have excess capacity, and certainly will design and build to handle your API quota.

As with user-facing services, you need to test the ability of your APIs in a environment that is representative help to make sure you can meet demand.

Where the API delivers personal or personal information you, once the data controller, must provide sufficient timeouts on any cached information in your delivery network.