How to Write a User Story for an API Product

One of the many questions I have received from my colleagues in product management is on what is the depth of a user story to be written when you are giving out an API as a product feature to the market. It is a contentious issue, and depending on the culture of the product organization, it differs. There are no right and wrong answers, but as a product manager, it is important you have a discussion with your product team and come to an understanding on what is required by you, and what they will do on their own.

There are certain organizations that require writing of an API specification by the product manager (or the corresponding role; product owner, business analyst). They might require you to write every single information, like what are the request methods, what are the error messages, etc. I am not going to talk about that. There are more than enough established practices on how to write those.

I am going to assume that you, as a product manager, provides the context of the problem to be solved with an API product, and defines the boundaries of it, to keep the team on track.

Who is the Customer of an API Product?

Duh! Developers. It is that simple.

But is it?

Developers are customers of an API product, yes, but isn’t that a bit reductive? Are all developers use the APIs in the same way to each other? Not really. Based on the scenario, there can be different types of developers, who use APIs in different contexts. They can be:

• Developers
• Solutions integrators
• Testers
• Partner onboarding personnel (e.g. in public API marketplaces)

Developers also care about convenience. If your API is difficult to use, the developers experience will suffer, making the adoption of your API in the market poorer. Therefore, you DO have to care about the experience of the developer, their context, to have a successful API product.

Structuring the Stories

There are many ways to structure an API story, but mostly, it is centered around sizing the story rather than having diverse resources being handled. I am not going to go into specific about the architecture of an API, the MVC models, etc. However, I would recommend you to consider the functionalities of an API as create, read, update and delete. This is not the exact way API methods are defined, but you do not have to be an expert about the API methods, just the ultimate object you are trying to satisfy with an API.

Now, to continue this tutorial, let us take an example of a API, that provides the users with the ability to manage information about nearby shops details in reference to latitude and longitude.

What are the functionalities that you expect from this API service?

For Shops:

1. Post the information about a shop.
2. Update the information about a shop.
3. Delete a shop from the service.

For Users:

1. Get the information about shops nearby a location.
2. Get more details about a shop when queried about it.

Ideally, I would recommend you writing one story for each of the above functionalities. This makes it easier for the API product, i.e. this set of APIs, to be published as a collection, and the developers to use the specific API that they want to achieve the desired functionality.

Of course, you can have a single story for all the shop functionalities and call it “[API] Manage shop information”. However, breaking down the story to each functionalities expected from the API makes the life easier for everyone.

Is the API feature an extension of the same functionality that you want to develop in GUI? Here, you can have two options: write the API functionality and the GUI functionality in the same story, or have two different story. This, you have to discuss with your team, but as a general rule, I would recommend you to have a separate API story if you want to go to market with the API as a separate feature / product.

Example way of writing a GUI functionality and an API functionality in the same story:

As a shop owner,

I want the products and prices of shops to be displayed in the shop information window,

So that the potential customers can know more about the shop and the products sold to make a purchase decision.

Acceptance Criteria:

• [criteria 1]
• [criteria 2]

API Requirement:

• Aforementioned functionality should be achievable via an API.
• [criteria x]
• [criteria y]

Writing the Base Story

Now, imagine a situation where I want the aforementioned APIs launched into the market as a separate product, as a platform. Here, I recommend to have a separate API story. So let’s start writing that.

Let’s take the functionality for the users, “get the information about shops nearby a location”.

As a developer who uses the ABC cloud platform to build applications,

I want to fetch the information about nearby shops via an API when I send lat-lon of a location,

So that I do not have to manually search for shops nearby a particular location when building my application.

Now, I could have simply put “as a developer” and hope that the product team understands the context the user is coming from. However, adding more context improves the team’s understanding about the user and improves the design of the API. For example, from reading this, the API designer would have gotten the context that this API should be secured via SSL, and it should have authentication as it is an API that will be available on a cloud platform.

When writing the expectation of the story, I can write the expectation from the API. Here, I have not specified which form of an API I would require, whether it is a REST API, or a GraphQL API. These design decisions are usually established in organizations, and the API designer should be making the decision on that.

Objective of the story can be written as what needs to be avoided as I have written. This can take many forms, and is open to your own interpretation of the API objective.

Writing Acceptance Criteria

Acceptance criteria can take many depths, and it is important to establish the required depth after discussing with the team. However, acceptance criteria should not be specifications, otherwise, there is no point of writing user stories in the first place. It should be instructive enough for the team to build up the design, but not restrictive in a way that eliminates designer’s thinking.

Let’s take some sample acceptance criteria for the story we considered.

• Should be able to send latitude and longitude in the API request. These fields are mandatory.
• Should return a list of shop names with the total number of shops available for the requested lat-lon. Should not send additional description about shops.

An important thing to highlight in API stories is, any inputs that you want the developer that is using the API to define, you should mention that in acceptance criteria.

You can also consider defining any standards API requires to be followed. For example, if you are creating a banking API, one good option would be to follow Open Banking API standards, and you can define this at the top of the acceptance criteria.

For acceptance criteria, what I have written should be enough. Unless you are required to write more specification details such as lat-lon character length, authentication method, etc. In that case, might as well write an API specification as it is more prescriptive. You are not forced to write a user story for an API.

Any Non-Functional Requirements

In a technical product like an API product, it is also important for you to provide input to the team on what are the non-functional aspects the users will find it desirable. Here, non-functional means the functionalities that are not related to the core expected function of an API. Expectations such as security, performance, redundancy, etc. can be introduced here that will guide the team to build an efficient product.

For the considered story, I would be defining the non-functional requirements as below.

• User must authenticate to use the API functionality.
• The API should support a load of 50 API requests per second without failing.
• API should process the request and respond within maximum 10 seconds in a cloud-to-cloud setup.

The non-functional expectations as above provides key input for the technical design of APIs, and is vital if you want to take an API product to the market.

So the Final API Story

As a developer who uses the ABC cloud platform to build applications,

I want to fetch the information about nearby shops via an API when I send lat-lon of a location,

So that I do not have to manually search for shops nearby a particular location when building my application.

Acceptance Criteria

• Should be able to send latitude and longitude in the API request. These fields are mandatory.
• Should return a list of shop names with the total number of shops available for the requested lat-lon. Should not send additional description about shops.

Non-Functional Expectations

• User must authenticate to use the API functionality.
• The API should support a load of 50 API requests per second without failing.
• API should process the request and respond within maximum 10 seconds in a cloud-to-cloud setup.

Conclusion

What I have mentioned above is merely a guideline. There can be many other, and sometimes better approaches to write API stories. However, so far, above has worked for me, so I recommend you to try it out.

It is the belief of some practitioners that APIs require specifications to be developed, going beyond simple user stories. However, I do not find this as a mandatory thing. If you believe your product team is matured enough to design an API, and is empowered, why not give a shot with a user story.