In case your organisation is managing the API, you will need certainly to manage the authorisation server.

Use application-level authorisation if you want 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 suitable for APIs holding personal or sensitive data unless you really trust your consumers, for example. another government department.

We recommend using OAuth 2.0, the open authorisation framework (specifically using the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, which are often used to help make API requests in the application’s behalf that is own.

To present authorisation that is user-level

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

For instance, 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 together with OAuth2, using its usage of JSON Web Token (JWT), may be suitable in many cases, for instance a system that is federated.

For privacy and whitelisting

Use whitelisting if you’d like your API to be permanently or temporarily private, for instance to operate a beta that is private. You can easily whitelist per application or per user.

You must not whitelist the IP addresses associated with 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. Rather than whitelisting, an HTTPS should be used by you egress proxy.

choose a suitable frequency that is refresh expiry period for the user access tokens – failure to refresh access tokens regularly may cause vulnerabilities

let 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 additional 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 much lower risk to your API if the 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. Try to find alterations in IP addresses or users APIs that is using at times during the the day. Browse the National Cyber Security Centre (NCSC) guidance to learn 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 true name of the API, namespaces and resources) should:

use nouns as opposed to verbs

be short, simple and easy clearly understandable

be human-guessable, avoiding technical or terms that are specialist possible

use hyphens instead of underscores as word separators for multiword names

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

Generally, all of your APIs needs to have its domain that is own 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 domain that is same

differentiating them through the use of namespaces.

The namespace should reflect the big event of government to be had by this API. Namespaces might be plural or singular, according to the situation.

Sub-resources must appear beneath the resource they connect with, but is going a maximum of three deep, as an example: /resource/id/sub-resource/id/sub-sub-resource .

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

You should use path parameters to recognize a specific resource or resources. As an example, /users/1 .

You need to only allow query strings to be used 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, for instance, avoid using the query string /users? >.

Query strings shouldn’t be useful for defining the behaviour of your API, for instance /users?action=getUser& >.

When iterating your API to include 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 should:

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 enables one to add fields to update functionality without requiring changes towards the client application)

make a new endpoint available for significant changes

provide notices for deprecated endpoints

New endpoints usually do not always need 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 in the URL or even 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, inform them when a field will not be there to allow them to make certain 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 this instance, 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 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 will want to test their application against your API before each goes live. If you have a read only API then that you do not necessarily need to provide a test service.

Supply them with a test service (sometimes referred to as a sandbox).

If for example the 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 expense of achieving this.

In case your API requires authorisation, as an example using OAuth 2.0, you’ll need to include this in your test service or provide multiple levels of a test service.

To assist you determine what to produce, do user research – pose a question to your API consumers what a sufficient test service would appear to be.

You really need to provide the ability to your development team to test thoroughly your API using sample test data, if applicable. Testing your API should not involve using production systems and buy essay online 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 ought to set quota expectations for the users in terms of capacity and rate available. Start small, in accordance with user needs, and respond to requests to boost capacity by making sure your API can meet up with the quotas you have got set.

Make certain users can test your full API up to the quotas you have got set.

Enforce the quotas you’ve got set, even if you’ve got excess capacity. This makes 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 take care of your API quota.

Much like user-facing services, you ought to test the ability of your APIs in a environment that is representative help to make sure you can easily meet demand.

Where in actuality the API delivers personal or information that is private, whilst the data controller, must make provision for sufficient timeouts on any cached information in your delivery network.