Don't just write the API spec, validate it too

In the past, I've written about the benefits of writing an API spec. I want to expand upon that topic in today's tip.

As a thought experiment, picture the most detailed and well-designed API spec you can? Maybe you're thinking about Stripe or some other well-known API. But now imagine that the actual API does not conform to that spec.

How useful is that documentation if you can't trust it? In this case, I think the spec is actually more frustrating than just having no documentation at all.

Recently, I had an experience that made me realize the importance of not just writing the spec, but also how critical it is to validate that you are abiding by the spec.

I was working on a greenfield project where a new API was being built. A separate team would be consuming the API, so this was a high-value opportunity to build an API spec.

For each new feature, I'd write the spec, get it approved, then we'd build the implementation. As we built the endpoints, we'd also write feature tests.

But for reasons outside the scope of this tip, these feature tests did not include validation that the requests and responses conformed to the API specification. This is something we normally do, but for this project, and at this point in the project, we were not yet enforcing spec validation.

We then had a lull in new feature requirements, so I took that opportunity to go back and add spec validation to our existing feature tests. I was absolutely shocked to find that we had multiple endpoints that did not conform to the spec.

Some of the deviation was minor, like not documenting that a 400 response could be returned. But others were quite big misses and would have really frustrated the front-end devs if they have bumped into it before I found and fixed it.

My point in all of this is not that I'm a sloppy programmer. (Honest I'm not!) But it's more that even with the best intentions, if you're not validating that your implementation matches your spec, you're not getting the full value out of the spec.

And it's so easy to add if you're already writing feature tests. It's literally only adding one trait to your test class.

Here to help,

Joel

P.S. Want an outsider to clone your project and make sure the README is complete enough to get started in one hour? I can help with that.