Guidance

Managing APIs to meet user needs

This guidance covers how to run your API as a service, including building the team you will need and the lifecycle of your API

• From: Central Digital and Data Office
• Published: 27 November 2020
• Last updated: 17 December 2020 — See all updates

If your API is providing a valuable function for users, you should treat it as a service and iterate it often, according to user research and new security developments.

The Service Manual contains agile delivery guidance for citizen-facing services to make sure they meet user needs. If you develop an API you will need to consider different things to those you consider when working on frontend services.

To make sure your API is effective and meets user needs, you should use the following sections of guidance:

• managing your API discovery
• managing your API alpha
• managing your public or private API beta
• managing your live API

Setting up a new API

Speak to your API management team to understand the API assurance and governance model in your organisation. If you do not have an API management team, you can contact the Data Standards Authority to discuss community assurance of your API.

When you consider setting up a team to develop an API, you should:

• check the government API Catalogue to see if there are components, design patterns or data sets that you can reuse from similar APIs
• read API technical and data standards and the related API design guidance
• understand the skills needed on your API and how these skill-sets differ to those who work on frontend web services
• understand your organisation’s publishing process for new APIs, to avoid developing in silos and to make sure you add your API to internal catalogues

Building skills in your API team

You will need the following roles in your API development team:

• developer
• technical architect
• product manager with technical and API understanding
• user researcher - combined with an understanding of UX (if building an API platform) and software development
• business analyst - these skills can support user research and quality control
• technical writer - this is a different skill to content design, so you’ll need a technical writer
• interaction designer or service designer - particularly if building an API platform, but also to make sure your APIs expose data in a way that is easy to use

Your API lifecycle

Your API will follow a lifecycle from the publication to retirement.

Every version of your API will likely be at a different point in its lifecycle. For example, v1.0 might be deprecated (retired), v2.0 might be live (stable) and v.3.0 might be in private beta.

You must make it clear to users where each version of your API is in its lifecycle. This will affect whether your:

• documentation is visible to users
• API endpoints are enabled, allowing users to make requests to the API version

You might also have API endpoints at different stages of maturity in the development lifecycle.

Published 27 November 2020
Last updated 17 December 2020 + show all updates

1. 17 December 2020

   Fixed a broken link and changed 'UX designer' to 'interaction designer or service designer'

2. 27 November 2020

   First published.