Using Spec-Driven Development to build consistent APIs

Spec-Driven Development is a software development process that uses the API specification as a guide to implementation. Inputs and outputs are turned into test cases to ensure that the API does everything it promises.

There is just one requirement to use this approach: Write the API documentation first. The most we can do beforehand the better, but we're not going Waterfall here. We can also use the benefits of agile methodologies to increment the documentation in cycles, as we do when coding.

Writing documentation first has some benefits:

1. Parallelize the development process. With the documentation in hands, both server and client can develop simultaneously. Mocking the API can improve this benefit.
2. Improves understanding of the whole. When writing the docs, you'll face edge cases, find inconsistencies and notice design problems. This will make the development process a lot easier and decrease the amount of rework.
3. Guide Development. Using the documentation as base for spec-driven development ensures that the API does exactly what it promises and, by delivering a great test coverage, decreases the amount of escaped bugs.

How to use Spec-Driven Development

With our documentation in hand we can start the development process. It’s very similar to BDD, with the difference that we rely on our API docs instead of user stories:

1. Choose a resource to develop;
2. Based on the specification, create automated tests to ensure the behaviour of the resource;
3. Code until the test passes;
4. Refactor until you're happy :)
5. Repeat!

Showing by example

Now that you already know what to do, I'll show how I'd do to create automated tests based on the documentation of a given resource. To do this, I'll use the OpenApi format to define the specification and RSpec to implement the tests.

Suppose we have an application that stores information about artworks and a new feature is required: transfer the ownership of a given artwork. The first thing we need to do to use Spec-Driven Development is to write the documentation of this feature.

After some discussion and review process we ended up with this:

The documentation of our endpoint

A simple PUT endpoint. Let's walk through each point of interest.

• parameters: just one, named id, that represents the ID of the artwork;
• requestBody: one integer representing the ID of the new owner;
• Three response cases: 200, 404 and 422.

These elements are important to build our expectations and create a good test coverage. I'll show you.

First of all, let's describe our endpoint:

Here we've described our endpoint and defined two arguments that will change according to our context: the action (or path) and the params that will be used. We've also declared what will be done before each expectation: a put method to our action, using the defined params.

To ensure our API implements every response case, let's define one context for each one:

As said, each context represents one of the response cases and defines the necessary conditions for them to happen. Doing this ensure that every single response case of our API is covered by our specs.

Finally, we define the expectations for each context:

Each context has one or more expectations. When the artwork is transferred we just need to ensure that the response is a 204 status. In the other two contexts, we also check if the error message is correct.

Now, our tests are ready and we can start our development process. I'll not cover it here, but remember: if during the development process you notice that something is wrong with some resource, go back to the documentation and change it first.

At the end of the development process you may not have a perfect API, but will have one with a great test coverage and that delivers exactly what it promises. That's what an API is about, right?

Want to learn more about development process and other related stuff? Follow our Goiabada Blog and enjoy a delicious mix of software development, design, and business.