Your API is hard to use. There will always be someone who will complain they can’t understand it. Your goal as an API producer is to make sure you’re delivering value to all consumers. How can you succeed? It feels like an impossible task, right? Yes, it’s hard to build the right API if you don’t really know who your consumers are. It’s hard to get to the right design when potential API consumers never share their feedback. It’s time to change this. Keep reading to explore one technique that I’ve been using with success.
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.
The only reaction you receive from API consumers is through support when they complain. Face it, you have never received their feedback during the design stage. You simply have no idea how new consumers would feel when using your API. You’re not alone, if that’s a relief. Many API producers are in that exact same situation. They design their APIs with the best intentions. However, later on, they find out that consumers aren’t happy with what they see. You, too, suddenly see that your API is hard to use. You know it because you got to the point of trying it yourself. And, even with all the internal knowledge you have, you couldn’t quite put together an integration easily. Yes, you can make individual API requests. Isolated requests. Not a real integration where you can actually solve a use case. How can you fix this mess?
One way to solve the lack of alignment between you and your API consumers is through prototyping. With a prototype, you can show consumers what your API would look like without having to implement it. So, the cost of having one is substantially lower compared to implementing the API before validating its design. You don’t even need to create a full API prototype. You can prototype just the operations you’re designing and validating. “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,” I wrote in October 2025. So, the idea is to create a prototype of the operations you’re designing, share it with the consumers who are interested, and use their feedback to iterate on the design. Every iteration makes the design and the prototype closer to what consumers expect from the API. Their feedback also, hopefully, gets more and more positive as they see the prototype’s behavior closer to their expectations. All this sounds good, right? Well, making it work isn’t hard, either.
Fortunately, we now have tools that make it very easy to turn an OpenAPI document into a working mock server in no time. And going from there into an API prototype takes just a couple of steps. “I started experimenting with using OpenAPI documents as the source of truth for all my API prototypes,” I wrote in October 2024. “I built a personal system for interpreting OpenAPI documents and using them as the only thing needed to run an API,” I continued. “You start with an empty document (...) and, as you update it, it’s reinterpreted, giving life to an API server.” You can do it yourself easily using, for example, the `openapi-backend` package from OpenAPI Stack. The goal is to be able to regenerate the API server whenever you make changes to your OpenAPI document. If you can do that and then share the URL of your prototype with your consumers, then you have everything you need.
If it all sounds positive and is so easy to put together, then why isn’t everyone already using API prototypes? One of the reasons is the pressure to deliver. Going through the API prototyping and validation process introduces friction to the delivery of API features. The longer you have to iterate before implementing your API features, the worse it gets. But, even in organizations where this pressure doesn’t exist, API prototypes aren’t something common yet. And the reason is that there isn’t a unified tool that lets you do all the things I’ve been describing here. Even though you can put it together yourself, it’s not as simple as using some off-the-shelf software. The summary is that, in many situations, the benefits of API prototyping don’t outweigh the cost of putting it together. Yet. Because there will one day when creating an API prototype will be as easy as creating an OpenAPI document. Until then, you have to make a bet on what’s already available.
Whether or not you end up using API prototypes is something only you can decide. My opinion, as you probably figured out by now, is that it’s much better to build the right API than it is to build a cheaper one that consumers don’t find attractive. However, I do understand that sometimes there are other market pressures. Until the cost of putting together and managing an API prototype becomes really low, I believe many of you will decide not to use one.
