Use application-level authorisation if you want to control which applications can access your API, but not which end that is specific. That is suitable if you want to use rate limiting, auditing, or billing functionality. Application-level authorisation may not be ideal for APIs holding personal or sensitive data unless you probably trust your consumers, for example. another government department.
We advice using OAuth 2.0, the open authorisation framework (specifically with all the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, which can be used in order to make API requests on the application’s behalf that is own.
To offer user-level authorisation
Use user-level authorisation if you want to control which end users can access your API. It is suited to dealing with personal or data that are sensitive.
For example, OAuth 2.0 is a authorisation that is popular in government, specifically because of 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 use of JSON Web Token (JWT), may be suitable in some instances, for example a federated system.
For privacy and whitelisting
Use whitelisting if you need your API to be permanently or temporarily private, for instance 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 could be provided Content that is using Delivery
Networks (CDNs) and load that is scalable, which count on flexible, rapid allocation of IP addresses and sharing. Instead of whitelisting, an HTTPS should be used by you egress proxy.
choose a suitable refresh frequency and expiry period for the 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 there is a good 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 additional security on APIs with user-level authorisation
ensure the tokens you provide have the narrowest permissions possible (narrowing the permissions means there’s a far 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. 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 learn how exactly to implement a monitoring strategy plus 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 instead 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, each of your APIs must have its domain that is own as each service possesses 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 namespace should reflect the event of government to be had by this API. Namespaces can be plural or singular, according to the situation.
Sub-resources must appear under the resource they relate with, but is going 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 should use path parameters to recognize a resource that is specific 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 shouldn’t use query strings in GET requests for identification purposes, for example, avoid using the query string /users? >.
Query strings shouldn’t be useful for defining the behaviour of one’s API, for example /users?action=getUser& >.
When iterating your API to add 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 really need to:
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 you to definitely add fields to update functionality without requiring changes to the client application)
make a new endpoint available for significant changes
provide notices for deprecated endpoints
New endpoints do not always need to accompany functionality that is new they still maintain backward compatibility
When you need which will make a backwards incompatible change you should look at:
incrementing a version number when you look at 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 time frame before discontinuing the old one
telling users of your API how to validate data, for example, let them know when a field will not be present so that they can make sure their validation rules will treat that field as optional
Sometimes need that is 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, for instance:
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 of those 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 would want to test their is edubirdies.org/buy-essay-online legal application against your API before each goes live. When you yourself have a read only API then you don’t necessarily need to provide a test service.
Give them a test service (sometimes known as a sandbox).
The cost of doing this if your API has complex or stateful behaviour, consider providing a test service that mimics the live service as much as possible, but bear in mind.
In case the 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 present, do user research – pose a question to your API consumers what a sufficient test service would seem like.
You should provide the ability to your development team to test thoroughly your API using sample test data, if applicable. Testing your API should not involve production that is using and production data.
For highly cacheable open data access APIs, a well-configured Content Delivery Network (CDN) might provide sufficient scalability.
For APIs that don’t have those characteristics, you should set quota expectations for the users when it comes to rate and capacity available. Start small, according to user needs, and react to requests to boost capacity by making sure your API can meet the quotas you have set.
Make certain users can test your full API up to the quotas you have set.
Enforce the quotas you have got set, even if you’ve got excess capacity. This will make sure that your users will get a experience that is consistent you don’t have excess capacity, and will design and build to deal with your API quota.
As with user-facing services, you ought to test the ability of your APIs in a representative environment to help 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.