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 want to use rate limiting, auditing, or billing functionality. Application-level authorisation may not be ideal for APIs holding personal or data that are sensitive you probably trust your consumers, for example. another government department.
We recommend using OAuth 2.0, the open authorisation framework (specifically utilizing the Client Credentials grant type). This service gives each registered application an OAuth2 Bearer Token, which is often used to create API requests in the application’s own behalf.
To give you user-level authorisation
Use user-level authorisation should you want to control which end users can access your API. It is ideal for working with personal or data that are sensitive.
As an example, OAuth 2.0 is a popular authorisation method in government, specifically because of the Authorisation Code grant type. Use OAuth 2.0 Scopes for more granular access control.
OpenID Connect (OIDC), which builds along with OAuth2, with its utilization of JSON Web Token (JWT), might be suitable in many cases, as an example a federated system.
For whitelisting and privacy
Use whitelisting if you prefer your API to be permanently or temporarily private, for instance to perform a beta that is private. You can whitelist per application or per user.
You ought not to whitelist the IP addresses of this APIs you consume. Simply because APIs can be provided using Content Delivery
Networks (CDNs) and scalable load balancers, which count on flexible, rapid allocation of IP addresses and sharing. Rather than whitelisting, an HTTPS should be used by you egress proxy.
choose the right refresh frequency and 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 when there is a 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 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 far 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 just like you’d closely monitor any website. Look for alterations in IP addresses or users APIs that is using at times of buy essay australia the day. Browse the National Cyber Security Centre (NCSC) guidance to learn how to implement a monitoring strategy together with specifics of simple tips to monitor the security status of networks and systems.
All API naming in URLs (including the name of your API, namespaces and resources) should:
use nouns in the place of verbs
be short, simple and 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 should have its domain that is own as each service features 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 them all from the same domain
differentiating them with the use of namespaces.
The function should be reflected by the namespace of government on offer by this API. Namespaces could be singular or plural, with regards to the situation.
Sub-resources must appear underneath the resource they relate solely to, but should go no more than three deep, as an example: /resource/id/sub-resource/id/sub-sub-resource .
If you reach a 3rd amount of granularity (sub-sub-resource), you really need to review your resource construction to see if it is actually a variety of multiple first or second level resources.
You should use path parameters to spot a specific resource or resources. For example, /users/1 .
You really need to only allow query strings to be utilized in GET requests for filtering the values returned from an resource that is individual for example /users?state=active or /users?page=2 .
You must never use query strings in GET requests for identification purposes, for example, stay away from the query string /users? >.
Query strings really should not 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 really need to minimise disruption for the users so they do not incur unnecessary costs.
To minimise disruption for users, you 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 add fields to update functionality without requiring changes to your client application)
make a endpoint that is new for significant changes
provide notices for deprecated endpoints
New endpoints usually do not always have 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 when you look at 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 is not going to show up so they can 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, 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. 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 may wish to test their application against your API before each goes 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).
If for example 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 price of carrying this out.
If for example the API requires authorisation, for instance using OAuth 2.0, need that is you’ll include this in your test service or provide multiple degrees of a test service.
That will help you determine what to produce, do user research – pose a question to your API consumers what a test that is sufficient would look like.
You should provide your development team using the ability to test thoroughly 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 provide sufficient scalability.
For APIs that don’t have those characteristics, you need to set quota expectations for the users with regards to capacity and rate available. Start small, according to user needs, and respond to requests to increase capacity by making sure your API can meet up with the quotas you’ve got set.
Make sure users can examine your API that is full up the quotas you’ve got set.
Enforce the quotas you have got set, even when you have excess capacity. This makes sure that your users are certain to get a consistent experience when you don’t have excess capacity, and will design and build to manage your API quota.
As with user-facing services, you really need to test the capability of your APIs in a environment that is representative help to make sure you can meet demand.
Where the API delivers personal or personal data you, given that data controller, must provide sufficient timeouts on any cached information in your delivery network.