API User Stories In Detail with Example

API User Stories are used for requirement capturing of a API Platform. Since APIs are technical component and usually an active user interface is not part of the main specifications, User Story capture need some creative ways to address the task. This approach will work for Rest APIs and any other API style. If you want to cover the basics of Rest API make sure you take a look at the home page.

Do not consider API just as a set of resources used by a developer to build a product. Users of APIs are much more than that. If we consider perspective of everyone and take a look at the platform in various aspects of functionality, accessibility and actors, we can create a complete set of API User Stories. The approach for User Story discussed here could be applied for all layers of accessibility. As a caution, I would say if you are simply looking for APIs to be used by a frontend layer just within your team – do not complicate, take what is necessary from the discussion here are stick to it.

In this article we will cover the following

• Checking Completeness of API Capture in various perspective
• Workflow from Business User Story to Development Completion
• Examples and Formats of Business, API Specification and API Development Stories
• Best Practices to follow in REST API User Story and Requirement capture

APIs generally follow an approximate hierarchy, even though there could be some overlap, based on IT, Business and Customer functionalities. Core IT APIs will be used to serve business APIs and business APIs will interact each other to form customer APIs. These APIs will belong to various access groups - Private or Internal access, Partner and Public. And these will be accessed by different actors. In a case study by McKinsey this approach is taken.

API User Stories based on Functionality

API User Stories for IT

Every organization has IT resources, policies and accesses to follow. There could be enterprise wide services meant to be used and reused. This forms the IT APIs. Identity and Access management, Data Services etc will fall under this group. While looking for User Stories you may have to do more than one pass to capture and cover all of these. It is possible that while working on Business User Story, you come across need for an IT User Story.

API User Stories for Business as Service

Whatever be the solution you are providing, it could be divided in to multiple services and each services will potentially expose several APIs. All such APIs will be covered by the User Stories here. If you are building a platform for a hotel business, reservation, lobby services, room services, customer care services will form verticals of the platform.

Your task will be to identify those platform verticals that naturally forms a logical grouping and then look for User Stories in each vertical.

API User Stories for Customer Journey

Platform is built to solve a business problem and Customers are the essential part of the equation. Look from the customer point of view and the services you will be providing to them. Usually, Business as Service APIs will interact to fulfill a Customer User Story.

In our example of hotel platform, if a Customer wants to reserve a hotel, it might interact between Reservation Service and Customer care.

If you are building a platform, as a Product Owner, it will help to think through these hierarchy to check completeness of APIs captured. It will also help to keep a spread sheet as initial analysis and brainstorming session. Use a format something like below. The list won’t be complete in the first pass, so identify and capture and fill in the API column and Functionality first, then fill in other details.

We have considered API from hierarchy level. Now, let us take a look from Access level. This is what you will fill in the Access column.

API User Stories based on Access

Public

These APIs are open to everyone. Organizations want to attract the developer community and encourage adoption of their platforms. Public APIs are for that purpose. Keep in mind that public access does not mean it could be accessed without any control. It is best when public APIs are published to be used with an API key. API key will help you track the usage and if needed throttle the usage. In short, public APIs are open to everyone with an API key and anyone can register and get an API key.

Partner

Partners bring win-win situations for the organizations. Your Partner wants to interact with your organization's resources or customers to provide a solution to better serve them. In out hotel example, online booking company could be hotel's partner. Booking company wants to know the available rooms for a given date. In these cases, APIs are the answer. Give your partners necessary APIs to fulfill their need.

Private

These APIs are only for your organizations internal purpose. Room cleaning alerts could be an example, where you integrate that API for build solution for effective room service tracking.

API User Stories Based on Actors

This APIs beyond developers. In the examples we walked through, it is evident how many actor roles or Persona uses the platform. As a User Story Developer, you need to identify every Persona, then start exploring and writing the stories for each. System Integrators, Partner Solution Providers etc are examples of Actors beyond developers.

Persona could belong to two categories

User Persona 

Any user that interacts with the system and derives value.

System Persona 

Another system that interacts with API to derive values.

Note that, exploration of User Story could be in any order that makes sense. And it makes sense to start with identifying the User Persona and their need. The order in which it is given in the article, makes the existence of various User Persona evident, and not necessarily an order to follow.

Proceeding with User Stories

At this point, we have considered system in various levels and captured APIs. This will be an iterative process. Now, let us move on to detail each User Story for the APIs we have identified.

By this time, you also have made decision which category API belongs to – is this for an internal application UI consumption or building a platform to expose to your partners.  We need a process and governance to make sure every stakeholder is in alignment with API being built. 

If this is to be used to an internal application User Interface? The process can be much relaxed. But if you are building a platform to integrate with external partners, or used by other enterprise teams, API being built must go through a governance body. Approach discussed here will work in either of the cases.

Let us walkthrough a scenario:

Here it is assumed that Product Owner, or the Business Analyst. PO is not Technical PO and may not understand REST API technicalities, but still understands basics of REST.  Also, a normal application building scenario is assumed - you are building an application which has UI that consumes an API and everyone, including API developer and UI developer, are in the same team. This assumption is for simplicity and will not restrict you in applying these in any other scenario such as working across teams or building API platform for an external partner.

As we discussed, User Stories normally take business requirement; however, APIs are technical and requires technical approach. But it doesn’t have to start that way. A Product Owner can keep business stories in the Product Backlog, just like any other stories are kept. Here you write story like any other one. Then it comes time to move it to Sprint Backlog, where development team addresses and start building each story.

Here is the difference:

You break down the business UserStory into total of three User Stories, if the business UserStory includes an API. If you are not sure if this business user story will result into an API, wait until sprint grooming sessions, where you will discuss this will your Technical Lead and rest of the development team.

Below is the format of three User Stories:

•  ‘API SPEC: Create Specification for API to XXXX’ Story
•  ‘API: Develop an API for XXX’
• Your original Business User Story – this could be used to build UI for the end customer

Essentially, we are saying you must build a REST API Specification and an independent story. This must be completed and signed off before building the actual API.

Technical Lead (TL) must understand the business User Story, work with the PO, and convert this into a Swagger Specification. Once completed it must have everything that is required for the API – path, actions, parameters, input, output, response, and error codes.

You should have a sheet for standard response code and error code kept in a centralized place for everyone to refer quickly and to make sure APIs are following standards.

For creating specification TL would need the following.

• Purpose of the User Story
• Input parameters or a screen layout and details to derive input parameters
• Output parameters or a screen layout after user performs operations on the initial screen
• Operations that would be performed by the user on this screen

Once these are available to the TL, it would be easier to convert it into a Swagger specification.

Once the Specification is completed, it goes for review and approval. In this case of App Dev scenario, Specification is demonstrated using Swagger UI and PO and UI developer agrees to the specification. If the agreement is reached Spec Story is closed. In case you are in Enterprise, or Platform scenario – this review has to go through appropriate governance before Specification is finalized.

Okay now we have API spec.

From this point, API Developer start developing API. With Specification you have in hand, you can mock API with sample data. For the same reason, UI developer can start ‘consuming’ APIs even before API is fully developed.

How to Write API User Story

Now that we have defined what should happen theoretically, let us look into an example. We are dealing here with UserStory specific REST API, it is assumed you generally know format of a User Story and Acceptance Criteria. Example here shows UserStories with Gherkin format Acceptance Criteria

Example

Let us look into a hotel website used by booking agent to see available rooms for a date and for a location of the hotel.

A PO would have a business user story from business perspective as follows.

It is a simple User Story and has only one scenario. This is good enough to demonstrate our purpose. It may or may not have a screenshot or a wireframe to demonstrate the intent. Also note that I have used acceptance criteria of Gherkin format. It helps generate Acceptance Test Cases, but for API I have used normal acceptance criteria. API is usually validated, and acceptance criteria tested as part of UI testing itself, since UI consumes API. We will cover API testing in a different post.

Now as this story gets in to Sprint backlog and you groom it with your Technical Lead and rest of the team including UI developer. Now, must be broken down in to two other User Stories.

This user story assumes an excel with all specification elements are created before the Swagger spec. This is helpful when reviewers are not very technical. You may cutdown this step if everyone understands Spec directly.

You may simply link your previous Business User Story for the Tech Lead to refer input and output details. It will avoid duplication of work. If you can dig deeper and create a list of input out

Here is the format of Spec spread sheet that could be used to review.

Swagger spec for REST API details out everything that is needed: 

1. Path/URI
2. Action
3. Parameters
4. Input
5. Output
6. Response and Error Codes

Spec should confirm to REST standards which a Tech lead should already know. As a PO only input you need to provide is input and output which is available from your business User Story. In the above example query parameters are used conforming to naming conventions.

Now our third User Story to Develop API from the Spec created.

Here you may refer API SPEC sand Business Story from here so that it is directly available from the current story.

Once these User Stories are completed, You have:

• API Spec,
• API code developed
• Business User Story addressed by completing UI development.

If you closely observe, you see that this user story only addresses fetch part (get all available rooms). This is typically GET of REST API. So, what about other operations?

It depends - if this is a small story your Spec and API development API can include other operations as well. Otherwise, split it into multiple stories for refining Spec with more operations and developing additional operations for the API.

You user stories should follow all the best practices as you would follow in any other case. It must follow INVEST (Independent, Negotiable (allow discussion), Valuable, Estimable, Small (or sized right) and Testable). If it is a complex Story, break down in to multiple.

Practical considerations

Above mentioned is a framework that you may need customization based on your situation and team’s comfort. But stick to the best practices.

You must come up with REST Specification before you code API.

Also, Spec must be reviewed and approved by stakeholders before proceeding with coding. If reviewers are not comfortable with API Spec in Swagger format, for approval an excel template filled with exact data points that will be converted to Spec may be used as interim. But deciding and developing spec before implementation is necessary.

When the system grows keeping track of API and parameter details can get difficult. Also, you need to comprehend the entire system. Looking at bit and pieces may result in breaking changes of API. To have a wider look, try to capture API system in terms of Entity relationship. You may also keep Entity and attributes of each entity in a spreadsheet. This will help you see the relationships and proactively think about the APIs being built.

Here are some Best Practices suggested for API User Stories and Requirement Capture.

Best Practice Checklist 

1. Specification first approach is used and agreed upon across team members
2. Developers should be trained on REST standards
3. Platform APIs must go through governance body and get approval
4. An Entity Diagram for reference is recommended. Also keep Entity and properties spreadsheet.
5. Keep a spreadsheet for standard REST response code and error code to be cross referenced by anyone to review and approve REST Specifications
6. Break fix must be as minimum as possible. For platforms proactive design is required
7. A Technical PO will help, but a Business PO will work if closely working with Technical Lead or Architect

Wrapping it Up

APIs are technical components without UI and it requires bit creativity to cover and write User Stories for API. You can look in to API platform to be built in various perspective of grouping by functionality, access and User Persona to extract allt eh stories for platform. Once you identify those stories put it in a clear format following the best practices for User Stories and it will give you a comprehensive list of User Stories that are well written.