Use application-level authorisation if you wish to control which applications can access your API, but not which specific end users. This is certainly 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 probably 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, that can be used to produce API requests on the application’s behalf that is own.
To produce user-level authorisation
Use user-level authorisation if you wish to control which end users can access your API. That is suited to coping with personal or sensitive data.
For example, OAuth 2.0 is a popular authorisation method in government, specifically with the Authorisation Code grant type. Use OAuth 2.0 Scopes for more granular access control.
OpenID Connect (OIDC), which builds along with OAuth2, using its usage of JSON Web Token (JWT), might be suitable in many cases, for example a federated system.
For whitelisting and privacy
Use whitelisting if you like your API to be permanently or temporarily private, for example to perform a beta that is private. You can easily whitelist per application or per user.
You ought not to whitelist the IP addresses for the APIs you consume. This is because APIs can be provided using Content Delivery
Networks (CDNs) and scalable load balancers, which rely on flexible, rapid allocation of IP addresses and sharing. Rather than whitelisting, you need to use an HTTPS egress proxy.
choose a suitable refresh frequency and 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 if there is a good 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
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 just as effective as your day-to-day security processes.
Monitor APIs for unusual behaviour exactly like you’d closely monitor any website. Look for alterations in IP addresses or users using APIs at unusual times of a single day. Read the National Cyber Security Centre (NCSC) guidance to learn just how to implement a monitoring strategy together with 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 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 instead of underscores as word separators for multiword names
For example: api-name.api.gov.uk .
Generally, all of your APIs must have its domain that is own as each service features its own domain. This will 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 essay writer deploy common services:
providing them all from the domain that is same
differentiating them by using namespaces.
The function should be reflected by the namespace of government on offer by this API. Namespaces could be singular or plural, depending on the situation.
Sub-resources must appear underneath the resource they connect with, but should go a maximum of three deep, for instance: /resource/id/sub-resource/id/sub-sub-resource .
If you reach a 3rd degree of granularity (sub-sub-resource), you should review your resource construction to see when it is actually a variety of multiple first or second level resources.
You need to use path parameters to recognize a resource that is specific resources. For example, /users/1 .
You should 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 shouldn’t use query strings in GET requests for identification purposes, as an example, avoid using the query string /users? >.
Query strings should not be utilized for defining the behaviour of your API, for example /users?action=getUser& >.
When iterating your API to add new or improved functionality, you really need to minimise disruption for your users so they 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 allows 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 to accompany new functionality if they still maintain backward compatibility
If you want to help make a backwards incompatible change you should consider:
incrementing a version number into 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, tell them when a field isn’t going to show up so 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 this situation, 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 exactly how you’ll notify them among 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 would want to test their application against your API before they go live. If you have a read only API then that you don’t necessarily need to provide a test service.
Give them a test service (sometimes described as a sandbox).
In case your API has complex or stateful behaviour, consider providing a test service that mimics the live service whenever possible, but bear in mind the price of carrying this out.
If for example the API requires authorisation, as an example using OAuth 2.0, need that is you’ll include this in your test service or provide multiple levels of a test service.
To help you decide what to offer, do user research – pose a question to your API consumers what a test that is sufficient would appear to be.
You ought to provide your development team utilizing the ability to test your API using sample test data, if applicable. Testing your API must not involve production that is using 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 ought to set quota expectations for your users with regards to rate and capacity available. Start small, according to user needs, and react to requests to improve capacity by making sure your API can meet with the quotas you have set.
Be sure users can test thoroughly your API that is full up the quotas you have got set.
Enforce the quotas you have set, even if you have excess capacity. This will make certain that your users can get a consistent experience when you don’t have excess capacity, and will design and build to undertake your API quota.
Much like user-facing services, you need to test the ability of your APIs in a environment that is representative help to make sure you are able to meet demand.
In which the API delivers personal or private information you, while the data controller, must provide sufficient timeouts on any cached information in your delivery network.