Beta This is new guidance. Complete our quick 5-question survey to help us improve it.

  1. Service manual
  2. Technology
  3. Application programming interfaces (APIs)

Application programming interfaces (APIs) expose some of a program’s internal functions to the outside world. This allows applications to share data without requiring developers to share all of their software’s code.

You should follow these guidelines when exposing a digital service as an API.

Build using your API

The simplest way to make sure your API is useful and consumable for your users is to build a website using your own API.

This will help you to:

  • model content and data in terms of bookmarkable resources
  • make sure you present data in a human-readable representation, as well as machine-readable representation

Use standards

You should consider an API to be a part of a website and provide links to machine-friendly formats.

You should also use standards like:

  • HTTP (Hypertext Transfer Protocol)
  • URLs (uniform resource locators)

You should also use established web patterns for authentication, for example by using OAuth 2.

Give each resource a bookmarkable URL

Expose data as a set of resources, offering a clean URL for each thing and each collection of things.

Only use query strings for URLs with unordered parameters, such as options to search pages.

You should consider creating URLs for different granularity of resources. For example, /members.json could return a list of names, while /members.json?detail=full could return detailed information about each member in a list.

These principles help to create a network of linked information online and from email, SMS, XMPP and other messages.

Use HTTP methods

You should make sure all HTTP GET requests are safe and that actions which change the state of a resource are conducted using a POST, PUT or DELETE method.

You should always offer a POST alternative and avoid HTTP methods that are not well defined, such as PATCH. Use PUT and DELETE with caution, as they are commonly blocked by firewalls, intranet proxies, hotel Wifi and mobile operators.

Representations are for the consumer

Offer content for each thing as human-readable HTML, with links to content in alternative machine-readable representations, like:

  • JSON for convenient processing in most programming languages
  • JSONP and JSON with CORS for client-side JavaScript
  • CSV for importing into spreadsheets
  • Atom for feeds

All text should be encoded as Unicode, following the Government Digital Service (GDS) Cross platform character encoding profile.

Where possible also offer other formats most suited to a specific domain, like:

Include hyperlinks to alternative representations such as link headers as well as in content. Consider also encoding metadata inside HTML content using semantic markup such as microformats, RDFa or schema.org.

The representations supported by an API for input vary depending on the complexity of the action, but where possible you should include application/x-www-form-urlencoded to allow the construction of simple POST forms.

Use names to reinforce conventions

You should make sure that names for fields, formats and path segments in a URL path are consistent across your API. You should establish conventions others can easily follow and reuse names widely used elsewhere on the web, for example using the Microformats naming policy.

Document your API

Building a website which exposes data through links and services through HTML forms encourages exploration and leads to discovery through hypertext.

You should provide documentation as a guide for developers wanting to use your API. Technical architects and service managers may also check your guide to see if your API meets their needs or to assess its security and reliability.

You should include:

  • clear reference information providing the functions, remote call and methods for your API
  • guidance to help developers experiment with your API
  • information about security, versioning and rate limiting so users can plan their commitment to using your API

Be open by default

You should aim to lower the barriers which prevent others from using your data, for example don’t demand registration or API keys for public data.

Open data increases the number of people able to use your data and service. This leads to feedback loops where consumers become motivated to resolve issues at source, feeding back issues and corrections to your service and its data.

If content requires authentication, use a standard authentication like basic authentication or OAuth, depending on the sensitivity of your content. You must always use HTTPS encryption.

Practice service evolution

Build for forwards compatibility by handling content that’s unexpected. The robustness principle (Postel’s Law) explains the ability for the web and internet to evolve, though you shouldn’t ignore protocol errors, corrupted content or invalidly formatted content.

Preserve backwards compatibility with existing consumers of your API by sending expected fields and employing sensible default values for missing fields. Avoid making semantic changes to the content, for example changing a title field.

If you can’t avoid large changes, communicate a breaking change by changing the URL. Use redirects so existing users find the new URL.

Consuming and using APIs

Sometimes the functionality your service needs will be provided by other parts of your organisation, other government departments or by reliable third parties via APIs.

Most modern digital services are built on top of a wide range of APIs. This allows each part of the service to focus on its core responsibility rather than constantly reinventing the wheel.

Code integration

When consuming APIs you should be careful to keep the integration with your code clean and distinct. This is important so that you can swap between providers or update to new versions of an API without making substantial changes to your core code.

You should use adapter code that’s entirely focused on interfacing with the system and mapping code. This will provide the linkage between your code’s domain model and the concepts and services provided by the API.

Testing your API

You should carefully consider how you intend to test your integration with the service.

In day-to-day development you need to be able to test your code without making (computationally or potentially financially) costly calls out to third-party services. You should find a way of providing mock versions of those APIs.

For full-system tests, you should build an automated mechanism to help you test the full flow, including the third-party service.

Example 1: email alerts

Many of the GOV.UK publishing applications send emails to provide alerts for users.

When running tests, the GOV.UK team doesn’t want to send lots of fake emails so they swap the normal email adapter for one that logs the emails it would have sent. This lets the GOV.UK team test the code is doing the right thing without depending on external services.

Example 2: Google Analytics

Parts of GDS’s Performance Platform code involve significant interactions with Google Analytics.

It wouldn’t be practical to test this by sending events to Google, waiting for them to be processed and then reviewing the results. GDS developers therefore built a mock service that can run alongside tests and provide a dummy version of Google’s API. This lets them check the right data is being sent.

Example 3: single sign-on

GOV.UK publishing systems make use of a single sign-on service.

In most tests the interactions with that service are mocked so the applications’ tests can be run in isolation. However, the GOV.UK development team also uses a suite of smoke tests that run in the preview environment and use dummy accounts to ensure that the full authentication and authorisation flow is working.

Depending on third-party APIs

By depending on a third-party API, you could tie your service’s availability to that of the third party. In some cases that may be acceptable, but often you need make sure you have a backup plan in place.

The details of that backup will vary depending on your service. You may need to offer the user the opportunity to use an alternative service, or queue the action to take place later. That could be an automated queue with software that monitors it and retries transactions, or a manual queue where someone follows up to collect further details.

If a third-party API failure affects your service, you should be clear with your users about what’s happening and find ways to limit the affect on users.

For example, if you’re using a third-party payment provider and another isn’t available, you might queue the transaction to try again later. That means you can’t offer users the same guarantee that their payment will be processed correctly and you should tell them this.

Further reading

You may also find the following guides useful:

Published by:
Technology community (technical architecture)
Last update:

Guidance first published