Prototyping APIs with OpenAPI
How can OpenAPI be a tool for quick, low-code API prototyping?
If you're serious about API design, you need to create prototypes on a regular basis. Prototyping is a technique that lets you easily get feedback from stakeholders without having to commit a team of developers. With a prototype that feels like the real API, potential consumers can share their experience, helping you advance your design. But how can you create API prototypes without writing a lot of code? I explored what's possible using OpenAPI as the source of truth. Follow me to see how you can use OpenAPI as a quick prototyping tool.
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.
The advantage of using OpenAPI as a prototyping tool is that you can use all the available tools that work with it. Linting, SDK generation, and documentation are among the types of tools you can get if you work with OpenAPI. The other advantage is that OpenAPI is both machine and human-readable. That means anyone can easily understand—and write—an OpenAPI document. You don't need any specific user interface to manipulate OpenAPI documents.
I've been using OpenAPI documents for all the APIs I work with. I feel I take the most from OpenAPI in the earliest steps of API design. It's when I'm first thinking of how an API should look like that I like to experiment and spin out a mock server. I make changes to the OpenAPI document and then try accessing the mock server to see how the design fits the needs of the project. However, I sometimes wish I could have something a bit better than a mock server.
The mock server I've been using is Prism. What I like the most about it is it gives you two options for generating mock data. You can either define the mock data from examples you define on your OpenAPI document, or you can let Prism generate the data using the Faker library. You can even configure how Prism generates the mock data using a vendor extension on your OpenAPI document. Through the x-faker vendor extension, you can specify which Faker method to use for a specific property. So, for example, if you wanted Prism to generate a random dog name, you'd use the faker.animal.dog method. You're not limited to animal names, as you can choose from hundreds of options.
Something else Prism does very well is validating requests to the mock. It simulates how a real API would behave when, say, you provide it with the wrong parameters. Or when you're trying to make a request to a non-existent operation. If a request fails to validate, Prism responds with an existing HTTP 422 or 400 response definition. If none exist, it will generate one itself, which follows the Problem Details for HTTP APIs (RFC 9457). Altogether, there's a lot you can do with Prism. And I use it a lot during my API prototyping activities. However, I wish I could go a couple of steps further and add some logic to what is now possible.
I started experimenting with using OpenAPI documents as the source of truth for all my API prototypes. Starting with the mocking approach I just shared, to then approaching a way to add more logic. So, I built a personal system for interpreting OpenAPI documents and using them as the only thing needed to run an API. It goes like this. You start with an empty document—let's call it openapi.yaml, but it could be anything—and, as you update it, it's reinterpreted, giving life to an API server. You don't need to write any external code for the API server to run. Once you have a valid OpenAPI document on the screen, you have the option to try any of the operations you're defining. If you do that, a pane opens on the right-hand side where you get to test the operation. You get immediate results. As you tweak the OpenAPI document, you can immediately test what you're changing.
Not having to leave my editor to see the results of what I'm changing is important. It lets me engage in a mode of experimentation that would be complicated if I had to switch applications. Being in a constant flow helps me understand what it feels like using the API, which is my goal while prototyping. As I define my API and add more operations, they immediately become available to try. Whenever I switch to another operation—either by clicking on it or moving the cursor—it shows on the right-hand panel, and a request is automatically made. Whenever I change anything, the request is refreshed, and I immediately see the response.
What about the extra logic I referred to earlier? I thought of using a vendor extension to let me add JavaScript code to any operation. Using something like x-handler would allow me to write code that could augment the generated mock. I could, for instance, have one operation create an entity and then have another operation list all entities. The feeling of using this API would be much more real than just using a lifeless mock server.
This tool doesn't exist yet. Not in a fully formed shape, at least. I do have a prototype working on my laptop. I feel I'm going in the right direction, as I use it almost every day as my API prototyping tool. I'll be writing more about it, so stay tuned.