Writing Great User Stories For Developing APIs

I recently received a great question from a viewer of my Creating Effective User Stories course. The viewer asked how she should approach writing user stories for team who would be creating APIs. For example, should the user story be written from the point of view of the API, such as “As an API, I want to…”, or should the persona portion of the user story be dropped entirely, focusing instead on only the intent and the justification.

As more and more teams find themselves tasked with creating APIs this is becoming a very common question. But luckily, there’s an approach to writing these types of user stories that can still help the team understand the intent of these stories without sacrificing their essence.

APIs Aren’t People

Most of know that creating an API persona for these types of stories simply doesn’t feel like the right answer. But explaining exactly why this isn’t the right answer can be harder to put your finger on.

To better understand why this feels wrong we have to remember some of the goals of user stories. First and foremost user stories are intended to improve collaboration with your team. However, they also have additional benefits, as well.

One of these additional benefits is to help you understand how the features you are designing will benefit the intended users of your product. Note the keyword there: users. This is critical, since without first understanding the users of your product, you can’t hope to design the features that will yield the most benefit to those users.

Another additional benefit is that well-crafted user stories help you understand the ultimate value that each story will be creating. This can help you can better understand if that value is worth the investment required to bring that story to market as well as when would be the optimal time to make that investment.

Note that neither of these benefits are possible if you don't have a properly-crafted and realistic persona already attached to each story. The lack of a realistic persona not only impedes your ability to make the necessary prioritization decisions as a product owner, but it also deprives your team of the context they'll need to make better informed technical decisions along the way.

Defining A Realistic Persona

So if creating a persona named API isn't the right choice for these types of stories then what is? The best choice is to identify the persona who will ultimately benefit from the value that the story will deliver and then attach the user story to that persona.

For example, imagine that you are creating an API that allows for conversions between different currency units. As part of this story you would like to convert between the Euro and the US Dollar. You could write the story as follows:

"As an API,
I want to convert between the Euro and the US Dollar".

While this user story does convey the action that you wish to accomplish it lacks critical context. Who needs to do perform this action...the API? That's not very helpful. And what about the why?

While this story does tell the team what you want achieve, it lacks the necessary context to help the team make better decisions in development as well as to help you decide where this story fits in your overall product strategy.

Understanding Who Stands To Benefit

Imagine that you discover that your API will be used by a commodities trading house. And furthermore, imagine that you have a persona called "Commodities Trader" who represents someone who trades global commodities. Let's revisit the story in this new light.

"As a Commodities Trader,I want to convert between the Euro and the US Dollar,
so that I can better understand how the price of my target commodity will be affected by currency fluctuations."

This version of the story gives us much more context to work with. For example, understanding that this conversion will be used for comparing currency valuations helps our team better understand what level of precision will be needed in their conversions. And understanding that this conversion is intended to be used for commodities trading gives you much more context as a product owner to understand where this story might fit in your overall product strategy.

For example, if the trading volume between the European Union and the United States is relatively low today then this story can probably be delayed in exchange for higher priority work. On the other hand, if this trading volume is currently high then your product would likely benefit from tackling this story sooner rather than later. And finally, since we now know who will be using the feature and why they will be using it, we now have more information to find other stories in our backlog that might complement this story and therefore should be delivered alongside of it.

Putting This To Work In Your APIs

Features should exist only to yield value to your product’s users and ultimately your stakeholders. And user stories should exist to give your delivery team the context they need to make better informed decisions along the way. But without a well-crafted persona attached to each user story, you risk investing your team’s effort only to deliver stories that completely miss the mark for both your users and your stakeholders.