by Adam Lowe on May 5, 2012

A question we often get at Hashrocket is, "story carding create, read, update and delete pages is easy but how do you story card an API without talking about implementation?" and the answer is that you can story card an API as interactions. You might end up describing more implementation or technical details and that is ok.

When I story card an API I give each request response pair a story and I treat the XML fields or JSON like I would a view in the application only instead of approved designs you have an approved API doc.

API Consumer creates a movie

  Given an API consumer
  When I submit a post to http://yourapp.com/movies/
  And I have filled in
  - title (required, limit to 50 characters)
  - description (limit to 100 characters)
  - url to movie file
  Then an asset is created
  And the system returns an http status code 201 created
  And the system returns the URI for the created movie


API Consumer sends a create request for a movie with no title

  Given an API consumer
  When I submit a post to http://yourapp.com/movies/
  And I have not filled in title
  Then an asset is not created
  And the system returns
  - an http status code 400 bad request
  - an error message that the title cannot be blank
  - the body of the request

Things to keep in mind are that you may have already put in place limits on character length if you built the GUI for these resources first and it would be redundant when you are writing the API stories. In that case they could be omitted from these stories. In the second story for the bad request I can get away with just saying that I did not fill in title because the other attributes are not required otherwise I would specify that I provided valid values for those fields as well.

Next I want to have a stories that cover a title too long error message and a description too long message since we validate those as well. We want to cover the golden path first but in order build an API that consumers will enjoy using we want to provide meaningful error messages for all of the things we validate against and could subsequently reject their request based on. When you have a specific story for each you will allow the users of your API to quickly identify issues with their requests and enjoy using your API. In addition to having a well structured RESTful API covering these cases will contribute an API with a good user experience.