If your organisation is managing the API, you shall want to manage the authorisation server.

If your organisation is managing the API, you shall want to manage the authorisation server.

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 ideal for APIs holding personal or data that are sensitive you probably trust your consumers, as an example. another government department.

We advice using OAuth 2.0, the open authorisation framework (specifically with the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, that can easily be used to produce API requests in the application’s own behalf.

To supply authorisation that is user-level

Use user-level authorisation should you want to control which end users can access your API. It is suitable for dealing with personal or data that are sensitive.

As an example, OAuth 2.0 is a popular authorisation method in government, specifically with all 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 system that is federated.

For whitelisting and privacy

Use whitelisting if you prefer your API to be permanently or temporarily private, as an example to operate a private beta. You can easily whitelist per application or per user.

You ought not to whitelist the IP addresses associated with the APIs you consume. Simply because APIs may be provided Content that is using Delivery

Networks (CDNs) and load that is scalable, which rely on flexible, rapid allocation of IP addresses and sharing. Instead of whitelisting, you should utilize an HTTPS egress proxy.

choose the right refresh frequency and expiry period for your user access tokens — failure to refresh access tokens regularly can lead to 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

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 as good as your day-to-day security processes.

Monitor APIs for unusual behaviour exactly like you’d closely monitor any website. Try to find alterations in IP addresses or users APIs that is using at times during the your day. See the National Cyber Security Centre (NCSC) guidance to discover just how to implement a monitoring strategy therefore the specifics of just how to monitor the security status of networks and systems.

All API naming in URLs (including the true name of one’s API, namespaces and resources) should:

use nouns as opposed to verbs

be short, simple and 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

For example: api-name.api.gov.uk .

Generally, each of your APIs must have its own domain, just as each service possesses its own domain. This will also avoid API sprawl and simplify your versioning.

If you provide multiple APIs and you have a company 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 all of them through the domain that is same

differentiating them with the use of namespaces.

The namespace should reflect the big event of government being offered by this API. Namespaces can be singular or plural, with regards to the situation.

Sub-resources must appear beneath the resource they relate genuinely to, but is going a maximum of three deep, for example: /resource/id/sub-resource/id/sub-sub-resource .

If you reach a third standard of granularity (sub-sub-resource), you need to review your resource construction to see if it’s actually a mixture of multiple first or second level resources.

You should 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 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, stay away from the query string /users? >.

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

When iterating your API to add new or functionality that is improved you really need to minimise disruption for the users so they usually do not incur unnecessary costs.

To minimise disruption for users, you really need to:

make backwards changes that are compatible possible — specify parsers ignore properties they don’t expect or understand to make sure changes are backwards compatible (this permits you to 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 have 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 into the URL or the HTTP header (focus on /v1/ and increment with whole numbers)

supporting both old and new endpoints in parallel for a suitable period of time before discontinuing the old one

telling users of your API how exactly to validate data, for instance, let them know when a field is not going to be there so that they can be sure their validation rules will treat that field as optional

Sometimes need that is you’ll make a more substantial 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 client that is old forever.

State how long users have to upgrade, and exactly 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 would 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 referred to as a sandbox).

If the API has custom writing complex or stateful behaviour, consider providing a test service that mimics the live service whenever you can, but bear in mind the price of carrying this out.

In the event the API requires authorisation, for example using OAuth 2.0, need that is you’ll include this in your test service or provide multiple amounts of a test service.

To assist you decide what to offer, do user research — pose a question to your API consumers what a sufficient test service would seem like.

You ought to provide your development team with the ability to test thoroughly your API using sample test data, if applicable. Testing your API must 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 need to set quota expectations for the users with regards to capacity and rate available. Start small, based on user needs, and react to requests to boost capacity by making sure your API can meet with the quotas you’ve got set.

Be sure users can test your API that is full up the quotas you’ve got set.

Enforce the quotas you have set, even though you have 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 can design and build to address your API quota.

Just like user-facing services, you ought to test the capability of your APIs in a environment that is representative help make sure you are able 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.