API User Story - card, conversation Confirmation, context

What is an API User Story?


Are you looking to get an idea of what an API User Story is about and understand if it would help to streamline the way you work in your business?


I have previously talked about  how an API platform can help grow your business.


API User Stories, created right at the start of the project life cycle, capture the requirements of an API platform. An API User Story captures a business requirement with defined acceptance criteria and expected outcomes.


An API User Story can be defined based on different aspects, for example:

  • The functionality of the API e.g. customer journeys
  • Software features e.g. code framework, logging etc
  • Access requirements for public / private / partner customers and each actor involved in the journey


Best Practices for API User Stories recommend The Four Cs.


An API User Story: The four Cs



  1. Card

First, an API requirement is defined as a Card by briefly defining: As an [actor], I want / need to [action] so that I can [benefit].


  1. Conversation

The next step is to identify the essential aspects which need to be defined on the card. This is achieved by engaging with others and collaborating in Conversation to identify the most important factors for this API User Story.


  1. Confirmation

Once the conversations are all done we have the Confirmation stage: to work out how to recognize and measure success. Confirmation defines the set of observable outcomes which should occur (and can be evaluated/tested) for each scenario.


  1. Context

Lastly is Context: where we consider the possible ways this solution could be utilized and understand the dependencies. This covers both pre-conditions and post-conditions from the requirement and solution perspective.



How does an API User Story fit into a project lifecycle?



To write a great API User Story, you need to understand the business requirements and artefacts, as well as expert conceptual knowledge.


  1. Artefacts

Source artefacts which help to understand new requirements include:

  • Business Requirement Specification: Captured by Business Analysts after discussion with Project team & Architects.
  • High Level Design / End to End Solution Design: Captures the E2E solution design covering the entire impacted application landscape.


However, not all API requirements start from scratch. In scenarios where an API User Story will be created for existing APIs, or during migration from legacy technology, we will also require:

  • API Specification Documentation: Defines the purpose of an API along with functional and technical overviews of the API. Interface details (request & response) form the core of this specification, along with error details. This specification may already include user story information along with example payloads for reference clients.


In the absence of any source artefacts for an existing API, we could reference:

  • API Test Suite: Test suites which were used to test the APIs contain the scenarios / API user story information.
  • API Low Level Design Documentation: This document focuses on the implementation of an API, contains basic information about the API, and various scenarios supported by the API.


  1. Conceptual Knowledge

Discussion with people who are knowledgeable & expert in the business area ensures the API User Story is in-line with business expectations. It can also highlight gaps in initial definitions.


Some people who may add value to your API User Story definition include:

  • Customers
  • Product Owner / Product Manager
  • E2E Solution Architect
  • API Governance Board
  • Domain Experts
  • Test Manager


To ensure a common understanding and expectation of the API User Story, it is recommended to follow a process for evaluation, feedback and sign-off. Recommended participants in this process are:

  • Product Owner / Product Manager
  • E2E Solution Architect
  • API Governance Board


Don’t forget the API Portal


A well-defined API User Story will clearly detail the requirements, set the right expectations and streamline the delivery of the new feature right from design to release.


Having said that, remember an API User Story does not replace the information in the API Portal (if you have one, or are planning to create one). The specifics for each API should always be part of the API Portal documentation to help developers and consumers understand use cases, run mocks, and more.



Find out More

At Sandhata, our consultants are experts in APIs, API management and API monetisation. We can help you create the right API strategy for your business.

Find out how we can help you take advantage of digital transformation. Surviving and thriving in today’s digital economy demands no less.

Contact us today.



The following two tabs change content below.

Anitha Govindasamy

Anitha Govindasamy is a Solution Designer at Sandhata Technologies. With more than 15 years in IT Industry, she brings in Middleware Integration Design expertise and is passionate to explore new ideas and innovations.

Latest posts by Anitha Govindasamy (see all)