API Contract Testing Made Easy

As software becomes increasingly complex, more and more companies are turning to APIs as a way to organize and manage their application's functionality.  Instead of being one monolithic application where all changes are released at once, now software can be made up of multiple APIs that are dependent upon each other, but which can be released separately at any time.  Because of this, it's possible to have a scenario where one API releases new functionality which breaks a second API's functionality, because the second API was relying on the first and now something has changed.

The way to mitigate the risk of this happening is through using API contract tests.  These can seem confusing: which API sets up the tests, and which API runs them?  Fortunately after watching this presentation, I understand the concept a bit better.  In this post I'll be creating a very simple example to show how contract testing works.

Let's imagine that we have an online store that sells superballs.  The store sells superballs of different colors and sizes, and it has uses three different APIs to accomplish its sales tasks:

Inventory API:  This API keeps track of the superball inventory, to make sure that orders can be fulfilled.  It has the following endpoints:

• /checkInventory, which passes in a color and size and verifies that that ball is available
• /remove, which passes in a color and size and removes that ball from the inventory
• /add, which passes in a color and size and adds that ball to the inventory

Orders API:  This API is responsible for taking and processing orders from customers.  It has the following endpoints:

• /addToCart, which puts a ball in the customer's shopping cart
• /placeOrder, which completes the sale

Returns API:  This API is responsible for processing customer returns.  It has the following endpoint:

• /processReturn, which confirms the customer's return and starts the refund process

Both the Orders API and the Returns API are dependent on the Inventory API in the following ways:

• When the Orders API processes the /addToCart command, it calls the /checkInventory endpoint to verify that the type of ball that's been added to the cart is available
• When the Orders API processes the /placeOrder command, it calls the /remove command to remove that ball from the inventory so it can't be ordered by someone else
• When the Returns API runs the /processReturn command, it calls the /add command to return that ball to the inventory

In this example, the Inventory API is the producer, and the Orders API and Returns API are the consumers.  

It is the consumer's responsibility to provide the producer with some contract tests to run whenever the producer makes a code change to their API.  So in our example:

The team who works on the Orders API would provide contract tests like this to the team who works on the Inventory API:

• /checkInventory, where the body contained { "color": "purple", "size": "small" }
• /remove, where the body contained { "color": "red", "size": "large" }

The team who works on the Returns API would provide an example like this to the team who works on the Inventory API:

• /add, where the body contained { "color": "yellow", "size": "small" }

Now the team that works on the Inventory API can take those examples and add them to their suite of tests.  

Let's imagine that the superball store has just had an update to their inventory. There are now two different kinds of bounce levels for the balls: medium and high.  So the Inventory API needs to make some changes to their API to reflect this.  Now a ball can have three properties: color, size, and bounce.  

The Inventory API modifies their /checkInventory, /add, and /remove commands to accept the new bounce property.  But the developer accidentally makes "bounce" a required field for the /checkInventory endpoint.  

After the changes are made, the contract tests are run.  The /checkInventory test contributed by the Orders API fails with a 400 error, because there's no value for "bounce".  When the developer sees this, she finds her error and makes the bounce property optional.  Now the /checkInventory call will pass.  

Without these contract tests in place, the team working on the Inventory API might not have noticed that their change was going to break the Orders API.  If the change went to production, no customer would be able to add a ball to their cart!

I hope this simple example illustrates the importance of contract testing, and the responsibilities of each API team when setting up contracts.  I'd love to hear about how you are using contract testing in your own work!  You can add your experiences in the Comments section.