A Simple API Design Walkthrough
How to prototype an API before you code
Jun 13, 2019
Legendary Broadway director Gower Champion walked into a rehearsal to find the cast standing around. They weren’t sure what to do in a scene, so they weren’t doing anything. The choreographer, who is supposed to know these things, sat puzzled in the audience. Surely Champion, who won five Tonys for choreography (and another three for directing), would have the answer.
Instead, Champion turned to the choreographer and said, “do something, so we can change it.”
There are many situations where you’ll find yourself paralyzed by indecision. In many cases, including API design, taking action is exactly the answer to unblock paralysis.
Frontend and backend teams are rarely in perfect step. Frequently, the team that wants to consume an API is ready long before there are any endpoints to call. You don’t want engineers standing around the stage without anything to do. It’s time to design something, which can then be iterated upon.
Production API decisions are forever. You may end up supporting clients consuming that API for years. Thoughtless action could make API maintenance unbearable, but only if decisions are permanent. During the API design phase, much like Broadway rehearsals, you may try things that never make it to production.
For example, you can use a tool like Stoplight to model your responses. Then stub out endpoints and request structures. This way, you design your API outside of code, with very little overhead needed to make changes. Take your API beyond conceptual and then you’ll be more likely to know what needs to change.
You need more than one star performer, whether you’re making a Broadway show or an API. Even if your company has an API architect, they won’t have all the market knowledge of the product teams, or data constraints insights of the engineers. When you start to design your API, create an object to which collaborators can react. You’ll need a place to log the feedback and conversation.
Every team has its own way of handling collaboration, even if it’s not a formal process. Some common approaches:
There are probably almost as many approaches as there are dev teams. The tools you use will determine who feels welcome in the discussion. In some cases, it may determine who even has access to the API design process.
Stoplight includes full team support, so everyone has access to the latest API design thinking. You’re more likely to get feedback from product, business development, or other relevant teams if there’s a comfortable place to collaborate.
A great Broadway show frequently includes actors, singers, and dancers. Similarly, you can call on diverse skill sets and roles to make your API successful.
As you design an API, you figure out the use cases it needs to support and how it will enable them. You get feedback from those who will use it and make adjustments. At some point, you’re ready to go to production, much like a well-rehearsed Broadway show. A live API brings all the design work into reality.
As API requests come into your production API, those consuming it should already know what to expect. Your design codifies the endpoints, request data, and responses of your API. You can use an OpenAPI document to communicate what’s possible with your API in a machine-readable way.
To confirm that your API is performing like you expect, use contract testing. Run test scenarios against your API to ensure it works like expected. Just as a choreographer might confirm that the planned steps are completed, you’ll ensure your development matches your design.