Use application-level authorisation should you want to control which applications can access your API, but not which end that is specific. It is suitable if you want to use rate limiting, auditing, or billing functionality. Application-level authorisation is probably not suited to APIs holding personal or data that are sensitive you truly trust your consumers, for instance. 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, and this can be used which will make API requests from the application’s own behalf.
To give authorisation that is user-level
Use user-level authorisation if you wish to control which end users can access your API. This is ideal for working 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 access control that is granular.
OpenID Connect (OIDC), which builds together with OAuth2, using its utilization of JSON Web Token (JWT), may be suitable in many cases, as an example a system that is federated.
For privacy and whitelisting
Use whitelisting if you would like your API to be permanently or temporarily private, as an example 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 using Content 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 a suitable frequency that is refresh expiry period for your 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 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 much lower risk to your API in the event that 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. Seek out changes in IP addresses or users APIs that is using at times of your day. Browse the National Cyber Security Centre (NCSC) guidance to find out simple tips to implement a monitoring strategy in addition to specifics of how to monitor the security status of networks and systems.
All API naming in URLs (such as the true name of your API, namespaces and resources) should:
use nouns rather than verbs
be short, simple and easy clearly understandable
be human-guessable, avoiding technical or terms that are specialist possible
use hyphens rather than underscores as word separators for multiword names
For instance: api-name.api.gov.uk .
Generally, every one of your APIs should have its own domain, just as each service has its own domain. This may 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 all of them through the domain that is same
differentiating them with the use of namespaces.
The function should be reflected by the namespace of government to be had by this API. Namespaces can be plural or singular, with regards to the situation.
Sub-resources must appear under the resource they relate solely to, but should go a maximum of three deep, for example: /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’s actually a mix of multiple first or second level resources.
You should use path parameters to recognize a specific resource or resources. For example, /users/1 .
You really 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 must never use query strings in GET requests for identification purposes, as an example, avoid using the query string /users? >.
Query strings really should not be utilized for defining the behaviour of one’s API, for instance /users?action=getUser& >.
When iterating your API to include new or functionality that is improved you ought to minimise disruption for the users so they try not to incur unnecessary costs.
To minimise disruption for users, you should:
make backwards compatible changes where possible – specify parsers ignore properties they don’t expect or understand to make certain changes are backwards compatible (this permits you to definitely 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 want to accompany functionality that is new they still maintain backward compatibility
When you need which will make a backwards incompatible change you should consider:
incrementing a version number into 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 time that is suitable before discontinuing the old one
telling users of your API how to validate data, for example, inform them when a field is not going to be there to allow them to make sure their validation rules will treat that field as optional
Sometimes need that is essay about education in usa you’ll make a bigger change and simplify a complex object structure by folding data from multiple objects together. In this case, 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 users that are long to upgrade, and exactly how you’ll notify them of the deadlines. For instance, 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 do not necessarily have to provide a test service.
Supply them with a test service (sometimes referred to as a sandbox).
In case the API has complex or stateful behaviour, consider providing a test service that mimics the live service as much as possible, but bear in mind the expense of carrying this out.
If the API requires authorisation, for example using OAuth 2.0, you’ll need to include this in your test service or provide multiple quantities of a test service.
That will help 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 ought 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 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 your users with regards to rate and capacity available. Start small, in accordance with user needs, and react to requests to boost capacity by making sure your API can meet the quotas you’ve got set.
Make certain users can test thoroughly your full API up to the quotas you have set.
Enforce the quotas you have set, even though you have excess capacity. This is why certain that your users will get a consistent experience when you don’t have excess capacity, and can design and build to handle your API quota.
Just like user-facing services, you need to test the capability of your APIs in a representative environment to help to make sure it is possible to meet demand.
In which the API delivers personal or information that is private, since the data controller, must definitely provide sufficient timeouts on any cached information in your delivery network.