Use application-level authorisation if you’d like to control which applications can access your API, but not which specific end users. That is suitable if you wish to use rate limiting, auditing, or billing functionality. Application-level authorisation is typically not suitable for APIs holding personal or data that are sensitive you really trust your consumers, for instance. another government department.
We recommend using OAuth 2.0, the open authorisation framework (specifically because of the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, and that can be used to create API requests from the application’s behalf that is own.
To offer user-level authorisation
Use user-level authorisation if you wish to control which end users can access your API. This can be suited to dealing with personal or data that are sensitive.
For instance, 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 granular access control.
OpenID Connect (OIDC), which builds in addition to OAuth2, having its utilization of JSON Web Token (JWT), may be suitable in many cases, as an example a federated system.
For privacy and whitelisting
Use whitelisting if you’d like your API to be permanently or temporarily private, for instance to run a beta that is private. You can easily whitelist per application or per user.
You should not whitelist the IP addresses associated with the APIs you consume. This is because APIs might 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, you should utilize an HTTPS egress proxy.
choose a suitable frequency that is refresh expiry period for your user access tokens – failure to refresh access tokens regularly can lead to vulnerabilities
allow your users to revoke authority
invalidate an access token yourselves and force a reissue if you have a reason to suspect a token has been compromised.
use time-based passwords that are one-timeTOTP) for extra 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 far lower risk to your API in the event that tokens are lost by users or compromised)
Your API security is only as effective as 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 using APIs at unusual times of your 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 just how to monitor the security status of networks and systems.
All API naming in URLs (such as the name of your API, namespaces and resources) should:
use nouns in place of verbs
be short, simple and easy clearly understandable
be human-guessable, avoiding technical or specialist terms where possible
use hyphens in the place of underscores as word essay writers separators for multiword names
As an example: api-name.api.gov.uk .
Generally, every one of your APIs needs to have its domain that is own as each service possesses its own domain. This may also avoid API sprawl and simplify your versioning.
In the event that 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 want to consider:
providing them all through the same domain
differentiating them by using namespaces.
The namespace should reflect the event of government being offered by this API. Namespaces may be singular or plural, depending on the situation.
Sub-resources must appear under the resource they relate to, but should go 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 need to use path parameters to identify a specific resource or resources. For 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 must never use query strings in GET requests for identification purposes, for instance, stay away from the query string /users? >.
Query strings shouldn’t be utilized for defining the behaviour of one’s API, for instance /users?action=getUser& >.
When iterating your API to include new or improved functionality, you need to minimise disruption for the users in order 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 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 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 within the URL or even the HTTP header (begin with /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, inform them when a field isn’t going to be present to enable them to be sure their validation rules will treat that field as optional
Sometimes you’ll need certainly to make a larger 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, 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 old client applications forever.
State how users that are long to upgrade, and just how you’ll notify them among these deadlines. As an 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 they go 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).
In case the API has complex or stateful behaviour, consider providing a test service that mimics the live service whenever you can, but bear in mind the expense 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 levels of a test service.
That will help you decide what to deliver, do user research – pose a question to your API consumers what a test that is sufficient would seem like.
You ought to provide the ability to your development team 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 possibly 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, based on user needs, and react to requests to boost capacity by simply making sure your API can meet the quotas you have set.
Be sure users can test thoroughly your API that is full up the quotas you’ve got set.
Enforce the quotas you have got set, even if you’ve got excess capacity. This will make sure 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 manage your API quota.
Much like user-facing services, you need to test the capability of your APIs in a representative environment to help make sure it is possible to meet demand.
Where in fact the API delivers personal or private information you, due to the fact data controller, must provide sufficient timeouts on any cached information in your delivery network.