User stories for API integration

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

A large amount of the software these days is 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 systems.  Sometimes it is a true two way exchange, but mostly it involves sending new data to, 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 another functional user.  We also need to keep our language simple and clear.  There are probably tens of thousands of ways that this could be written.  Here is just one suggested phrasing:

As a shopper I want to add my shipping address,
  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