An Interactive Approach to API Prototyping Using OpenAPI
Can OpenAPI be the source of truth for real-time API prototyping?
I built a real-time API prototyping tool from scratch. A few weeks ago, I shared my initial idea of how my ideal API prototyping tool should work. At the end of that article, I wrote that the tool "doesn't exist yet in a fully formed shape." I started putting a few things together locally on my laptop until I got to a point where I had a working tool. Keep reading to learn how I did it.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
I initially entertained the thought of building the whole thing from scratch. But then I realized it would take too long, and I wanted to be able to use something right away. It didn't have to be perfect. However, I wanted to try it and improve it over time with as little effort as possible. So, I investigated how I could use existing tools, libraries, and solutions to get to a point where I had a working prototyping tool. But before we get into all that, let’s first reflect on the importance of API prototyping.
The ability to have a simple version of an API to experiment with and get feedback from stakeholders is the main value of API prototyping. With an API prototype, anyone can see how an API would feel without having to engage a team of engineers. API prototypes let potential consumers test use cases and provide valuable feedback about request parameters, payloads, and responses. API prototyping is more than mocking because it allows you to bake in functionality. You can, for instance, let consumers create resources and then read them. Basically, the whole CRUD operations should work on a prototype.
Back to my experiment, I couldn’t find any tool that would provide what I needed. I usually start designing an API by sketching on an OpenAPI document. I start with something simple, sometimes reusing something already available similar to what I want. I then make sure the OpenAPI document is valid and use it to generate a mock. With the mock, I run some tests on an API client to see how a consumer would feel. Then, I repeat the process until I’m happy with the result. At this point, I share the OpenAPI document with stakeholders. They then generate a mock and test it using their favorite API client. Then, they share their feedback, and I go back to sketch mode, where I repeat the whole process again.
The process is quite convoluted, in my opinion. The two things I can improve that take the most time are the effort it takes to go from sketching an API design to having a mock and the feedback loop with stakeholders. While the latter has to do mostly with collaboration, I felt I could improve the former by being able to see results immediately while prototyping. That’s exactly the pain point I set out to solve. My goal was to convert the steps of sketching, validating, mocking, and testing an API design into a single seamless flow where I could experiment freely until satisfied.
So, how does it work? I'm using Visual Studio Code as my canvas because it's easy to extend with plugins. The plugins I'm using are GitHub Copilot and 42Crunch's OpenAPI Editor. Copilot gives me the ability to translate ideas into a rough OpenAPI description that I can then mold to my needs. The OpenAPI Editor helps with linting and has a fantastic feature called "Try it," which is what makes the whole flow work. "Try it" opens a panel with an API client that lets me immediately make a request to the API operation I'm working on.
To make all this work, I implemented a dynamic API server behind the scenes. The server uses openapi-backend from OpenAPI Stack and dynamically serves whatever I have on my OpenAPI document. There are a few more bells and whistles there that let me go from mocking to prototyping, and I also added Faker support to help me quickly generate request parameters. Altogether, it's a relatively simple solution that is almost what I had in mind when I started my experiments.
What I'm doing now is extending this solution to provide me immediate feedback without having to click on "Try it." That would even make the flow feel more interactive. To a point where I can actually see how changes on the OpenAPI document influence how consuming the API feels. I'll be sharing my progress here, as usual, so stay tuned.