Use application-level authorisation if you’d like to control which applications can access your API, but not which end that is specific. This really is suitable if you want to use rate limiting, auditing, or billing functionality. Application-level authorisation may not be suitable for APIs holding personal or data that are sensitive you really trust your consumers, as an example. another government department.
We recommend 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, that can easily be used to produce API requests from the application’s own behalf.
To present user-level authorisation
Use user-level authorisation if you want to control which end users can access your API. It is ideal for working with personal or data that are sensitive.
For instance, 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 along with OAuth2, having its utilization of JSON Web Token (JWT), may be suitable in some instances, for instance a federated system.
For privacy and whitelisting
Use whitelisting if you need 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 should not whitelist the IP addresses associated with the APIs you consume. It is because APIs could 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, an HTTPS should be used by you 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 one-time passwords (TOTP) 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 only just like your day-to-day security processes.
Monitor APIs for unusual behaviour exactly like you’d closely monitor any website. Search for changes in IP addresses or users APIs that is using at times of the day. Read the National Cyber Security Centre (NCSC) guidance to discover how to implement a monitoring strategy in addition to specifics of just how to monitor the security status of networks and systems.
All API naming in URLs (including the true name of your API, namespaces and resources) should:
use nouns in the place of 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
For instance: api-name.api.gov.uk .
Generally, all of do my homework your APIs should have its domain that is own as each service has its own domain. This will also avoid API sprawl and simplify your versioning.
In the event that you provide multiple APIs and also you have a business case that means you’ll deploy common services across them, such as common management, authentication and security approaches, you may need to consider:
providing them all from the domain that is same
differentiating them with the use of namespaces.
The namespace should reflect the function of government to be had by this API. Namespaces can be plural or singular, with respect to the situation.
Sub-resources must appear underneath the resource they relate to, but should go a maximum of three deep, for instance: /resource/id/sub-resource/id/sub-sub-resource .
If you reach a third level of granularity (sub-sub-resource), you really need to review your resource construction to see if it is actually a variety of multiple first or second level resources.
You should utilize path parameters to recognize 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 must never use query strings in GET requests for identification purposes, for 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 include new or improved functionality, you need to minimise disruption for the users so that they do not incur unnecessary costs.
To minimise disruption for users, you ought to:
make backwards compatible changes where possible – specify parsers ignore properties they don’t expect or understand to make sure changes are backwards compatible (this enables you to add fields to update functionality without requiring changes to the client application)
make a endpoint that is new for significant changes
provide notices for deprecated endpoints
New endpoints do not always want 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 when you look at 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, for example, tell them when a field is not going to be there so they can be 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 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 client that is old forever.
State how long users have to upgrade, and how you’ll notify them of those 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 may wish to test their application against your API before they go live. When you yourself have a read only API then you don’t necessarily have to provide a test service.
Provide them with a test service (sometimes known as a sandbox).
In the event your API has complex or stateful behaviour, consider providing a test service that mimics the live service whenever possible, but keep in mind the price of doing this.
If your API requires authorisation, for example using OAuth 2.0, you’ll need certainly to include this in your test service or provide multiple degrees of a test service.
That will help you decide what to provide, 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 utilizing 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.
For highly cacheable open data access APIs, a well-configured Content Delivery Network (CDN) may possibly provide sufficient scalability.
For APIs that don’t have those characteristics, you really need to set quota expectations for your users in terms of capacity and rate available. Start small, according to user needs, and react to requests to boost capacity by simply making sure your API can meet the quotas you’ve got set.
Make sure users can examine your full API up to the quotas you have set.
Enforce the quotas you have got set, even when you’ve got excess capacity. This is why certain that your users are certain to get a experience that is consistent you don’t have excess capacity, and will design and build to carry out your API quota.
As with user-facing services, you should test the capacity of your APIs in a representative environment to help make sure you are able to meet demand.
Where in actuality the API delivers personal or information that is private, due to the fact data controller, must make provision for sufficient timeouts on any cached information in your delivery network.