Use application-level authorisation if you’d like to control which applications can access your API, but not which specific end users. This is certainly suitable if you wish 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 actually trust your consumers, as an 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 are often used to make API requests regarding the application’s behalf that is own.
To give you authorisation that is user-level
Use user-level authorisation should you want to control which end users can access your API. This is certainly suitable for working with personal or sensitive data.
For instance, OAuth 2.0 is a authorisation that is popular in government, specifically using the Authorisation Code grant type. Use OAuth 2.0 Scopes for more granular access control.
OpenID Connect (OIDC), which builds on top of OAuth2, using its usage of JSON Web Token (JWT), might be suitable in some instances, for instance a federated system.
For whitelisting and privacy
Use whitelisting if you prefer your API to be permanently or temporarily private, for example to operate a private beta. You can whitelist per application or per user.
You ought not to whitelist the IP addresses for the APIs you consume. The reason being 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. Rather than 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
let your users to revoke authority
invalidate an access token yourselves and force a reissue if there is a 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
ensure 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 only as effective as your day-to-day security processes.
Monitor APIs for unusual behaviour exactly like you’d closely monitor any website. Try to find alterations in IP addresses or users APIs that is using at times during the a single day. See the National Cyber Security Centre (NCSC) guidance to learn how exactly to implement a monitoring strategy as well as the specifics of how exactly 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 place of verbs
be short, simple and clearly understandable
be human-guessable, avoiding technical or specialist terms where possible
use hyphens as opposed to underscores as word separators for multiword names
For example: api-name.api.gov.uk .
Generally, each of your APIs must have its domain that is own as each service features its own domain. This can also avoid API sprawl and simplify your versioning.
If you provide multiple APIs and you have a business case this means you’ll deploy common services across them, such as common management, authentication and security approaches, you may want to consider:
providing all of them through the same domain
differentiating them through the use of namespaces.
The namespace should reflect the event of government being offered by this API. Namespaces might be singular or plural, with respect to the situation.
Sub-resources must appear beneath the resource they relate to, but should go a maximum of three deep, for instance: /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 utilize path parameters to identify a specific resource or resources. For example, /users/1 .
You should only allow query strings to be used in GET requests for filtering the values returned from an resource that is individual for example /users?state=active or /users?page=2 .
You shouldn’t use query strings in GET requests for identification purposes, as an example, stay away from the query string /users? >.
Query strings shouldn’t be employed 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 need to minimise disruption for your users so that they try not to incur unnecessary costs.
To minimise disruption for users, you need to:
make backwards compatible changes where 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 to the 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 functionality that is new they still maintain backward compatibility
When you really need to make a backwards incompatible change you should look at:
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 time period before discontinuing the old one
telling users of what is essaywritersite.com/write-my-paper-for-me your API how to validate data, for example, tell them when a field isn’t going to be present for them to make certain their validation rules will treat that field as optional
Sometimes you’ll want to make a more substantial change and simplify a complex object structure by folding data from multiple objects together. In this instance, 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 long users have to upgrade, and how you’ll notify them of 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. For those who have a read only API then you don’t necessarily need certainly to provide a test service.
Supply them with a test service (sometimes described as a sandbox).
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 the cost of carrying this out.
In case your 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.
That will help you decide what to produce, do user research – ask your API consumers what a test that is sufficient would look like.
You really need to provide the ability to your development team to test your API using sample test data, if applicable. Testing your API must not involve production that is using and production data.
A well-configured Content Delivery Network (CDN) may provide sufficient scalability for highly cacheable open data access APIs.
For APIs that don’t have those characteristics, you ought to set quota expectations for your users with regards to capacity and rate available. Start small, according to user needs, and react to requests to improve capacity by making sure your API can meet the quotas you have got set.
Be sure users can test thoroughly your full API up to the quotas you have 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 consistent experience when you don’t have excess capacity, and can design and build to address your API quota.
Much like user-facing services, you really need to test the capacity of your APIs in a representative environment to help make sure you can easily meet demand.
Where the API delivers personal or private information you, given that data controller, must provide sufficient timeouts on any cached information in your delivery network.