Managing your API discovery
How you can test and manage your API when it is in discovery.
Do an API discovery to gain understanding of the context and the wider environment in which your API will operate.
Before starting, you should check the government API Catalogue to understand what APIs already exist in government and what best practice is available. You should also read the API technical and data standards.
During the API discovery, you will need to identify:
- your potential users - to understand their needs, the opportunities your API can deliver to them, and who their end users are (your users might include software developers, data scientists or designers)
- the systems and services that will use your API so you understand where your API will sit in the wider technology stack/architecture - this will make sure your API is not siloed and is as useful to services as possible
- constraints of any technology your API will need to rely on or integrate with
User research during your API discovery
As with a frontend service, you’ll need to do user research in your API discovery to understand who your users are and what’s going on when they access your service. You might choose to have an experienced user researcher in your discovery team.
Be mindful of user research fatigue when doing user research with your identified API users. This can happen because APIs often:
- serve different purposes but have the same set of users, meaning you will ask the same users for feedback multiple times
- have a limited set of users to engage with, unlike frontend services where typically user research could involve engaging with tens of thousands of users
User research is valuable even with just one or two developers, as long as you make sure they do not have too much influence over the API design.
You might choose to agree to a partner arrangement with a number of developers at an early stage. They can validate things like whether data is being shared in the right format. Although a developer partnering to test an API might need to work through defects and deal with breaking changes, they can benefit from the direct engagement and support that comes from being a partner.
Defining success metrics for your API
You should consider a number of factors when defining what you will improve for your users by developing your API. Be quantitative in your approach. For example, you might need to:
- reduce costs of integration with your system, and the time it can take
- make sure your users only get the data they want, minimising the amount of data you share
- improve the performance of your system, such as the time it takes to respond to data requests
When deciding whether to proceed to alpha
Before you proceed to alpha, you’ll need to consider:
- performing a cost-benefit analysis, considering how much it will cost to deliver your API, the cost savings the API will bring and the user needs it will address
- defining the metrics you’ll use to measure the success of your API
- engaging with external stakeholders, including those in the API community, and internal stakeholders
- the team members you will need for the API alpha, which often includes a technical writer, user researcher and business analyst, as well as the development and architect team