Writing an API Story

What are API stories?

Many programmers and designers have been exposed to the notion of stories to help build services and interfaces. A common example of this practice is found in the user story concept that comes from the early days of the Agile software community. A good explanation of user stories and how they can be used comes from Mike Cohn of Mountain Goat Software. He defines user stories as “short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system.” Cohn’s stories typically follow a common template: “As a TYPE-OF-USER, I want SOME-GOAL so that SOME-REASON.” This template approach makes it easy to generate stories that are both short and have perspective. We’ll be using this same approach for our API stories.

API stories have up to five sections:

1. Purpose: This is a short statement that defines the reason this API exists and what it does.
2. Data: This section lists all the data properties (inputs and outputs) involved in fulfilling the API’s purpose.
3. Actions: This section lists all the actions the API is expected to

...