User stories for API integration

This is one of several short articles on writing better usr stories with ScopeMaster.

A large amount of the software that is written these days is about integrating different sub-applications to create a new compound system.  Consequently the software requirements will often talk  about one system talking to another.  This software integration is typically through APIs, such as RESTful APIs including microservices.

So let us turn our attention to writing user stories that are about integration.  Here is a simple example:  a user on an commerce application reaches the address input section.  They can enter their postcode, 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,
 we send the postcode to the Posctode_lookup_api to retrieve the full address

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 from this the two key steps involve and therefore 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).  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”.  The external “body” whilst it may be an API, is in fact, a type of user, or functional user to be specific.