Most elements you create during API design are wasted. If they’re not validated by stakeholders, they end up being replaced with new ideas. This is a situation that happens because, as an API Designer, you work on entire APIs. Even when you iterate on a design, you do it holistically, taking the feedback and adapting the whole API accordingly. I’m not saying this approach is wrong. After all, it’s what many of us have been following to launch successful APIs. However, it makes the API design stage take longer than it should. What if I tell you that API prototyping can be an incremental process? What if following this incremental process would make the whole API implementation faster and less wasteful? Keep reading to learn more.
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
A large part of designing an API consists of sharing your work with stakeholders and making changes until everyone is satisfied. Anyone will tell you that you shouldn’t move to the implementation stage of the API lifecycle until you’re absolutely sure the full design is validated. Well, as good as this approach looks, it comes with its own challenges. The first one has to do with time. You can only advance to the implementation stage after you spend time designing, obtaining feedback, improving the design, until you find validation. After all this, you share the API definition with your implementation team, who will take it from there. And that’s where the second challenge often happens. In many situations, you don’t need (or don’t want) to implement the whole API. Perhaps you want to do incremental rollouts. Or you don’t have time to implement everything at once. In any case, the full API design gets outdated very easily and, sometimes, will have to be reviewed. One of the reasons for a redesign is the lack of implementation feasibility, which is the third challenge. Sometimes you find out too late that some parts of the API design simply aren’t practicable to implement and run. As you can see, these three challenges increase the odds of wasting substantial parts of an API design. All because you can only enter the implementation API lifecycle stage once you have your API fully designed. What if you could move to implementation earlier than that?
You’re free to move between the design and implementation API lifecycle stages as often as you like. The solution to avoid wasting so much API design is to focus on one feature at a time, validate it with stakeholders, and move it immediately to implementation before trying to design anything else. I like to call this API prototyping approach “just-in-time.” It’s the very minimum necessary prototype you need to validate one single assumption and unlock any subsequent decisions. Just-in-time, or JIT, API prototyping starts with a question you need to find an answer to. Questions can be as simple as “Does the article creation operation work well to import existing documents?” or more complex, like “Will developers be able to implement authorization using OAuth 2.0 Dynamic Client Registration?” Each question translates into a JIT prototype that you then share with your stakeholders. They will experiment with the prototype with the goal of answering your question. If they’re not happy with what they see, you iterate on the prototype. If, on the other hand, the answer is positive, you can move the prototype to the API implementation stage and pick the next question. Every time you move a JIT prototype to the implementation stage, you’re incrementally building the API, one feature at a time. The API building process becomes a stream where features go through the lifecycle, one at a time, and just when you need them.
Following the JIT API prototyping approach shouldn’t be complicated. You start by identifying what you need to learn or, in other words, what uncertainty you need to resolve. With that information, you begin by conceptualizing the API feature you’re prototyping. A concept is a low-fidelity API prototype that you can share with stakeholders. You can create it using an OpenAPI document, JSON files with inputs and outputs, or even just a markdown file explaining how the API feature would work. At this point, you simply want to validate naming, structure, and usability before investing more time and resources. Then, move to an interactive prototype that stakeholders can interact with. The goal is to let stakeholders test the prototype and provide feedback. This time, the prototype needs to be high-fidelity because you want stakeholders to perceive what they’d feel with the real API feature. You can use tools like Stoplight Prism, Scalar Mock Server, or Wiremock, as long as they let you create a mock of your API feature. Finally, after a positive validation, share your learnings and the API definition document with the implementation team so they take it from there. “What can go wrong?” you might ask.
Even though the JIT API prototyping approach has many benefits, it can also present a few disadvantages. The first one is related to the fact that it targets short-term activities, one at a time. Because of that, there’s the risk of generating inconsistencies in the larger design over time. The second one has to do with the amount of work an API design team can handle. If there are multiple JIT API prototyping projects running in parallel, there’s a risk of overloading a team, or even duplicating part of the work. Finally, because the produced work is incremental, there’s a risk of generating too many API versions unnecessarily. All these risks can be mitigated, though, if you have the right discipline and your API design and implementation teams are aligned.
It’s up to you to decide if the benefits of agility and high learning speed outweigh the disadvantages that JIT API prototyping has. Depending on the size of the API you’re designing, you might want to consider JIT or a traditional prototyping approach. In the end, what really matters is that you can design and implement APIs that meet the needs of your users.