The Five Steps of API-First Design

And why API-First Design should be a part of your next web service project 

Some of the greatest inventions have occurred by accident, but when it comes to creating amazing web services, intentionality is the name of the game. And there’s not much more intentional than API-First Design. 

See, web services built without intention often suffer in regards to quality, such as slow delivery and rife with errors. And once put into place, low-quality web services are expensive to update.

But what is API-First Design?

From a high level, API-First Design is a purposeful approach to building high-quality web services in a way that avoids the pitfalls of an ad-hoc build. This approach can be broken down into five steps:

• treat the API of your web service as the standout principle
• appoint product ownership for the API to ensure a core focus on quality
• design the API contract before coding the web service
• build the frontend and backend alongside one another based on the API contract.

The Five Steps of the API Process

1. Treat the API of your web service as a first-class citizen.

API-First Design is like a lot of great things—it takes time, effort, and money to do correctly. That means learning a new process, having dedicated folks on the project, and realizing that it’s an ongoing process. 

But, if you’ve looked at all options and API-First Design is the way to go, then it’s time to put all you have behind it. In practice, that will require committing to the process by getting buy-in from your entire organization. You’ll also need to clear some space in both your organization and budget to ensure you get the most out of your work. 

2. Appoint product ownership for the API to keep the focus on high quality.

Quality products always begin with having a product owner, and it’s essential that your API receives the same star treatment. See, building out an API without leadership means that changes will occur in a more haphazard way, leading to poor quality. But, with a product owner, you’ll keep the focus on what’s best for the build and best for the web service overall. 

And since this person is going to need to get stakeholders involved from both a technical and non-technical perspective, the role doesn’t have to be a developer or architect. In fact, their most important role is to advocate for your particular process to ensure that the goals are prioritized and met. 

3. Design the API contract before building the web service in code.

The next important step is to design the API before writing code. You’re going to want to create something that both your team and stakeholders can understand. It doesn’t have to be super fancy—think sticky notes or a good old-fashioned whiteboard session. Remember, this isn’t coded, and it’s vital that everyone on your team, regardless of their role, is able to understand what is being created and is able to add suggestions.

As your design solidifies, translate the API contract to a machine-readable format, such as OpenAPI or GraphQL Schema. This format will have major payoffs in the next step.

4. Automatically generate documentation, client/server stubs, and mocked backends from the API contract.

A lot of time spent designing and creating documentation doesn’t feel very productive, as the documents are stored somewhere and never referenced again. That’s why it’s important to store your API contract in a machine-readable format like OpenAPI or GraphQL Schema. These formats automatically generate a number of extremely useful artifacts that will help your development process go faster.

5. Build the frontend and backend in parallel based on the API contract

Usually, frontend and backend development occurring at the same time can be a slippery slope that leads to a poor quality product. But this is where the API contract comes into play. This API contract prevents frontend and backend developers from interpreting a loose specification differently because the specifications are so well designed from the start. 

The API contract is basically your North Star. Changes will still occur, but the API contract will keep you on the right track.

If done correctly, your web service will be consistent, reusable, well-documented, and easy for developers to use. 

Don’t Settle for Anything but the Best

Your web service is a valuable resource for your organization, both from a logistical and financial standpoint. If you’re curious to learn more about API-First Design, check out our ebook, API-First Design: How some of the most important work is done before the first line of code is even written, or reach out and chat with a Nerd. We’ll be happy to help!