In the RESTBucks example, the authors present a useful state diagram that describes the actions a client can perform against the service.
Where does such an application state diagram come from? Well, it’s derived from the requirements, of course.
Since I like to specify requirements using examples, let’s see how we can derive an application state diagram from BDD-style requirements.
Example: RESTBucks state diagram
Here are the three scenarios for the Order a Drink story:
Scenario: Order a drink Given the RESTBucks service When I create an order for a large, semi milk latte for takeaway Then the order is created When I pay the order using credit card xxx1234 Then I receive a receipt And the order is paid When I wait until the order is ready And I take the order Then the order is completed Scenario: Change an order Given the RESTBucks service When I create an order for a large, semi milk latte for takeaway Then the order is created And the size is large When I change the order to a small size Then the order is created And the size is small Scenario: Cancel an order Given the RESTBucks service When I create an order for a large, semi milk latte for takeaway Then the order is created When I cancel the order Then the order is canceled
Let’s look at this in more detail, starting with the happy path scenario.
Given the RESTBucks service When I create an order for a large, semi milk latte for takeaway
The first line tells me there is a REST service, at some given billboard URL. The second line tells me I can use the POST method on that URI to create an Order resource with the given properties.
Then the order is created
This tells me the POST returns 201 with the location of the created Order resource.
When I pay the order using credit card xxx1234
This tells me there is a pay action (link relation).
Then I receive a receipt
This tells me the response of the pay action contains the representation of a Receipt resource.
And the order is paid
This tells me there is a link from the Receipt resource back to the Order resource. It also tells me the Order is now in paid status.
When I wait until the order is ready
This tells me that I can refresh the Order using GET until some other process changes its state to ready.
And I take the order
This tells me there is a take action (link relation).
Then the order is completed
This tells me that the Order is now in completed state.
Analyzing the other two scenarios in similar fashion gives us a state diagram that is very similar to the original in the RESTBucks example.
The only difference is that this diagram here contains an additional action to navigate from the Receipt to the Order. This navigation is also described in the book, but not shown in the diagram in the book.
Using BDD techniques for developing RESTful APIs
Using BDD scenarios it’s quite easy to discover the application state diagram. This shouldn’t come as a surprise, since the Given/When/Then syntax of BDD scenarios is just another way of describing states and state transitions.
From the application state diagram it’s only a small step to the complete resource model. When the resource model is implemented, you can re-use the BDD scenarios to automatically verify that the implementation matches the requirements.
So all in all, BDD techniques can help us a lot when developing RESTful APIs.
| Reference: | Behavior-Driven RESTful APIs from our JCG partner Remon Sinnema at the Secure Software Development blog. |
