A template for API user stories

[Marc Abraham]

Does anyone have any suggestions on a good template to formulate API user stories?

Just to give you rough example of where I got to so far:

Given that we have 1 data set that underpins the API and which contains all data

Given that we have 1 set of API end-points through which this data set can be accessed

As an internal user who wants to be able to view all available data

When I access the API

Then I get to view all the review data available through the API

Any practical suggestions would be very much appreciated, many thanks!

[Morgan Hall]

I don't see any reason to treat API user stories differently than any other system.  

I am a proponent of the "As a <role> I want <something> so that <reason>" form of user stories.  The other key for me is to break them down until they are very granular and deliverable.

I avoid the use of  "all" in user stories because it assumes knowledge about what "all" is.  Be specific to the point where you have everything called out individually and then can maybe wrap up what "all" means.  All data might include metadata that you don't actually want to expose via a public API for some reason.  By being explicit, you'll have an easier time writing the API and writing automated tests for the API.   

When doing a user story session, I will take a few shortcuts. Start with assumptions like you've laid out and then add sections that are all the same role so that you aren't writing "As a developer" over and over again, but if those details make it into a project management tool or task board, I make sure to write the role in so that the story is stand-alone and complete or at least triggers the conversation to flesh out the problem further.

Hope this helps,

Morgan

[Nick Panagopoulos]

If your team's goal is to develop an API in support of a GUI, then it's best to have the user be written from the user's perspective.
"As an account manager, I want to list the accounts I manage, so that I can understand the scope of my responsibility."

If your team's goal is to publish an API to expose to other developers, then the format is still the same.
For a new API
"As a developer, I want to use an API that can list the accounts for an account manager, so that I can display the list of accounts to the account manager"

For enhancing an existing API
"As a consumer of the listAccounts API, I want to retrieve the account location for each account, so that I can show it on a map."

When we didn't follow standards
"As a standards board member, I want the listAccounts API to return location as a standardized coordinate, so that the APIs return location in a standard manner. "