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 accomplish.
4. Rules: This section lists any rules the API is expected to enforce. For example, “The companyId must be globally unique.”
5. Processing: This section lists any processes the API is responsible for handling. For example, “Each time a company record is updated, a log record will be written.”

Here’s an example API story for BigCo’s Company API.