The Importance of OpenAPI Contracts

openapi text

When designing an API we’re usually focused on the problem at hand.

“I need to create a collection for the pet shop that lets the web app easily see how many doggies are in the window… GET /doggies… that should return a list with dogId, breed, age, color… yes… that works…”

But then you get into details like, should “color” be an enumerated list or freeform text?  Can any of these be NULL or just empty strings?  Do we have standards for these already? And… wait a sec… do we have another API that already returns a list of dogs that could be modified to show a list based on location?  That is, do we actually need a new API?

To be clear about those choices you need to create those definitions and then share it with other teams.  The most common and portable structure currently is the OpenAPI contract, but whether you’re using older Swagger yaml docs or current OpenAPI json files, the point is to enable collaboration on a few things:

Readability: We want both technical and non-technical audiences to be able to read the contract. This means we need to be able to import it into different tools to display the contract in reader friendly formats.   This lets a broader audience comment and make sure that the API is going to meet the business goals.

Automated Tests: To build APIs that work with other APIs we need to make sure they’re following the same rules.  They need to all share the same common patterns, naming conventions, error responses, and they need to fit in with other APIs; it’s not just making sure we’re not duplicating work or inventing new things, it’s also making sure that our new API doesn’t conflict with other APIs that other teams are building.

So, how should you build your OpenAPI contract? There are two schools of thought.

Create the Contract with an Editor: Tools like Restlet Studio and Stoplight.io give a nice visual editor to build up the entire contract from scratch.  With extensions like linters (analysis tools that flag bugs or style errors), you’re able to produce a contract that’s standards compliant pretty quickly and easily.

The downside is that there can be challenges with importing that OpenAPI contract into your development environment if your standards don’t take into account how different frameworks deal with different definitions.  Over time the linter needs to be adjusted to balance the realities of code and the demands of business, which requires a collaborative team that is able to work through that initial pain.

Let the Code Create the Contract: Developers often prefer to start by using frameworks like Spring which allow them to start “scaffolding” their API by writing code.  This gives the developer a testbed where they can play with it as they develop it.  They can then export an OpenAPI contract from that code and share it with the team.

Often times it’s faster for a developer to use a framework to create this scaffolding, but then the resulting OpenAPI contract is ultimately not standards compliant. Just as with creating the contract first and finding inconsistencies with standards and programming frameworks, there will be a need to collaborate and refine those standards.

But even when the standards and the code environments are in sync, the frameworks won’t have the linter embedded, and you will always have to go back after submitting the contract for review and make changes to the code.

The question for the developer centers on velocity.  Does scaffolding the API first, and then coming back and making changes based on business requirements actually save time or create more work?  Is it really faster to build code first, even if it turns out the entire project is stopped because it turns out there was another solution in another part of the company?

There is no easy answer. This is why we run sprints and regularly see how much time we’re spending on different tasks.  If it turns out we’re spending way too much time struggling with a tool like Stoplight, then we might try the code first model.  If we’re not getting releases done because we’re rewriting code over and over, we might want to try the document it first model.

But, at the end of the day, the OpenAPI contract is the primary artifiact, the source of truth for what this API does and what it looks like.  It’s a fantastic way to get engagement and tear down silos and while integrating the contract into the process at the beginning might take a little change and getting used to, the benefits for building an API Platform that works as a single, well-oiled machine are incalculable.