Better user story for integration

User stories for API integration

How to write a better user story for integration. This is one of several short articles on writing better user stories with ScopeMaster®.

A large amount of software nowadays involves integrating different component-applications to create a new system. Consequently the software requirements will often refer to one system linking to another. This kind of integration is usually about sharing data between the software applications. Sometimes it is a true two-way exchange, but mostly it involves sending data from one application to another, or looking up data from an external system. This software integration is typically through APIs, such as RESTful APIs and often using microservices.

So let us turn our attention to how to write a better user story for this kind of integration. This is one area where I do quite like the examples of Mike Cohn. Here is a simple example: a user on an ecommerce application reaches the address input section. They can enter their postcode, and a lookup to an external service is performed. So how do we best write this kind of user story?

Firstly we need to recognise that a connected system is generally another functional user. We also need to keep our language simple and clear. There are hundreds if not thousands of ways that this could be written. Here is just one suggested phrasing:

As a shopper I want to add my shipping address, using the
  Posctode_lookup_api to retrieve the full address from a postcode

In this case we have generated two functional steps in the user story. One for creating the address and another that performs the external lookup. ScopeMaster is able to identify these two functional steps, determine the functional intent and therefore create a good estimate of the functional size.

Exchanging data with a RESTful API typically follows a CRUD (create, read, update, delete) or (put, get, post, delete) pattern. It is important to recognise when defining and sizing a user story that we recognised we are sending data out, and getting a response back from an external “body” (or vice-versa). The external “body” whilst it may be an API, is in fact, a type of user, or functional user to be specific.

Learn more on how to write quality user stories for integration

Alternative Wording

There are many ways to write the same user story, perhaps hundreds of ways. So what we describe here are just examples. You can for example write the story from the perspective of the external system (with which we are integrating) as a user of our application e.g.

As the postcode service I can respond to requests 
and send address data on receipt of a postcode.

or we can write the same from the point of view of the user of our application.

As a shopper I can retrieve my address from the 
external postcode service when I enter a postcode.

Both are valid approaches. We recommend the latter for two reasons:

It focuses on the actual user’s experience.
It is written from the perspective of our application, not the external application.

Remember when you write an integration between two applications you may have to develop code in both places and test it independently and as a system.