If you’re running a project within your organisation to deliver an API to multiple other teams or users, and you’re used to working in an agile-ish way, you might have been unlucky enough to have heard something like the views below:
- APIs are a “purely technical” delivery.
- You won’t need to do user research as APIs don’t really have “user needs”.
- APIs don’t iterate when they’re delivered, they’re essentially “once and done”.
- You probably won’t need a Product Manager in the team.
If the above strikes a chord, I’d like to humbly disagree with each and every one of these statements and suggest that there’s a different way to consider things.
I’ve worked with a large number of organisations delivering “enabling services” via APIs, allowing data or transactional systems to be accessed programmatically by other teams inside or outside the organisation. Based on these experiences, neglecting the role of product management, user research and service design in API development is both pretty common and also makes a successful delivery a lot harder, but luckily it’s not that hard to fix either.
Where are the users?
If you’re delivering an online service like an e-commerce site, or a public sector service like taxing a car, then it’s often not too difficult to understand where your users are. They are the ones who buy your stuff or use your service directly to get what they need.
For APIs though you need to think a little wider. Why? Usually you’re providing an API service directly to one set of users, quite often software developers, or perhaps data scientists, who then use your API to deliver something else to some other set of users. That means that typically you’ve got two or more layers of users, and you need to somehow consider all of those layers of users and how they interact to optimise an API delivery.
Public API development
Consider a common public API scenario with two layers of users. Ultimately it’s the customer or end-users who need to be catered for, as they are at the heart of delivering business value. However, our first set of users are the developers who will “use” the API directly, in external organisations, all potentially working in different ways, on different sets of services to different groups of customers in the outside world.
So in this first scenario we need to understand the needs of the developers, but by proxy also understand the needs of their users, who we will likely never meet directly.
To give a concrete example, imagine we’re working in a payment services company, designing an API to take payments online. We need to understand our direct customers, those who are building e-commerce services and who will use our APIs directly to process payments. They might need a robust, easy-to-use, well documented system, in addition to having an API which provides access to the payment-related features they need to pass on to their customers. However, we also need to make sure our APIs are able to help them meet their customer needs, who could be a myriad of different other organisations depending on their customer base, and might be focussed on everything from a wide range of payment options, to a clear statement of charges on their bank account.
APIs for enabling services or platform teams
Another common scenario is where an “internal” API is being built by a platform team for consumption by other teams to enable them to access data or transactional capabilities. In this case the API will only be consumed by people in the same organisation as the team building the API, but those developers still have needs to cater for. They will also likely in turn be providing a service to other teams within an organisation, perhaps a finance or customer service team. It’s also possible that those teams will be dealing with people outside the organisation, customers or users who will have their own needs and expectations.
So if you’re looking to build a team to build an API service, somebody in that team needs to span and understand multiple domains, and in particular must understand the concerns and needs of developers across each of those groups.
It’s the Product Manager who owns the vision for how what is delivered will meet these, but understanding the service characteristics of the consumers may well require both user research to understand the users, and also service design to understand how things fit together.
Note I’m saying “user research” and “service design”, rather than “user researchers” and “service designers” here. Whether you need a dedicated person with a specialised skillset to look at these problems really depends on the existing skills in your team and the context of the delivery.
A user researcher for example will bring an armoury of techniques and a thorough approach to user research, but if your current start point is “our developers just put some API endpoints on a database”, getting anybody in the team to find and talk to at least the first group of users to understand what they want will be a step forward.
What do developers typically need
So how do you find out what the developers who will use your service need? The short answer is “you need to ask them”, and there’s no substitute for good user research.
However, after having done this a few times, there’s a bunch of things that tend to come up again and again. You’ll need to verify these in some way of course, but consider the list below as a good starting point:
- It has a feature-set which is aligned to the user needs and business problem set of the teams who will be using it.
- It reduces the work your developer customers need to do to implement the needs of their internal customers.
- It is reliable and robust.
- Ideally, “it just works”. For example, the service is built cloud-native and scales to reasonable levels of load without complicated negotiations ahead of implementation.
- Again ideally, the API team has taken care of some of the hard work around security or service transition tasks.
- It has transparent, clear metrics on usage, performance and cost.
- Friendly, knowledgeable support is available to support delivery and operation.
- Great documentation is easily accessible.
- It’s easy to onboard and gain access to API endpoints.
- It has an easily understandable, probably non-novel implementation, and works with existing libraries using standard protocols (for example Swagger / OpenAPI).
- It is available in the right environments and it’s easy to add access to new environments.
- Test data in early stage environments is easy to create, destroy and change.
- The API object model and returned data models are as simple as possible.
- If there are already technical standards in place that make sense to follow, you should do so. Unless there’s a really good reason to be different, forcing developers in teams to consume your API in a “special” way is going to be annoying.
Not all of the above are 100% guaranteed to be needed, but it is a good starting point for discussion if you’re looking to save some time.
Note also the recurrence of the word “easy”. For platform teams building enabling services, initially getting people to access things via your API can be a job of persuasion. Like all great products, the more friction-free you can make the whole process, the easier it is to sell the idea to other teams.
Iterating over time
Of course, as with any development story, it doesn’t end there. If you consider your API as a product like any other, it may be in a competitive or evolving space. The role of product management is to steer development in the right direction, understanding competitors if necessary, and of course keeping engaging with users.
This brings in a number of thorny issues, which include:
- You’ll need to work out who is “on the hook” for keeping these running smoothly and performing maintenance, which seems obvious, but in my experience “orphaned” APIs which gradually become a mystery to all around them are not uncommon.
- You’ll need to understand their ongoing usage, which likely means periodically analysing the usage data, and also checking in on the users to understand if they’re still happy. Quite often the context of delivery will evolve, and if an API feature-set doesn’t evolve too, you’ll end up either with unhappy customers, fewer customers, or a complex series of multiple workarounds in user-land.
- You’ll need to understand how to deliver changes. You’ve now got developers who’ve built their code on the assumption that your API will work a certain way. Change that and you’ve now got a whole heap of unhappy customers. From a technical perspective API versioning is going to be critical, but you’ll also need to be finding ways and channels to engage with your users in a structured way.
Summing up
You might be looking at the above and thinking “jeez, that looks like a whole heap of effort”. And yes, of course, this is more work than banging out an endpoint and throwing it over the wall to your users. Consider the above though and the net effort and cost over time is probably a lot less. You’ll be avoiding the work needed to fix a crisis, overhaul a failing service, or win back departed customers.
The key to success is understanding the right moment to invest the effort in the above steps, when you’ve got confidence it will pay back, and then gauging the right frequency to revisit and iterate over time, and that’ll be different depending on the situation you’re in.
As ever it’s a balance to make sure you’re doing enough product thinking, while maintaining an agile approach to delivering value to the end user, no matter which group they’re in, as early as possible.
This article was first published on LinkedIn in September 2024.