Chapter 7: Prototyping APIs

Design and Build Great Web APIs — by Mike Amundsen

Sketches are simple explorations that can lead us to discover the design details that are most likely to solve our API problem.

One step past sketching is whats called prototyping. Prototypes are more than simple drawings or snippets of JSON or HTML. Prototypes have more detail, more depth and more information in them. Unlike sketches — which are just lines on paper — prototypes are physical models of design. They are multi-dimensional.

They help us see how parts of the design relate to each other and how our proposed API design fits with other APIs. That’s what prototyping does for us — it adds dimension and detail to our API designs.

What Is an API Prototype?

A prototype is a multidimensional model. These models can be the source material or the guide for creating the final full sized object you’re creating. It helps you work out details at a small scale.

Advantages of Prototyping

In the physical world, creating a one-off custom outfit or even mass-producing off-the-rack clothing can be time-consuming and involve a great deal of investment in materials, setup of production equipment, and validation of the final product for safety and usability. This can also be true in the virtual world of APIs. We need to allocate a budget for the work, put together a team and setup build-test-deploy pipelines as we bring the API to life. It can be costly and frustrating to discover errors in the design if you’re already in the process of creating the final product.

API prototyping is a way to discover — and fix — possible problems early and at a low cost. It can save lots of time and money later in the virtual world of software.

Limits of Prototyping

As valuable as prototyping can be, it has its limits.We can only test basic design. We wont be able to gain much information about how resilient or reliable the API will be until we build a more robust version of it. ITs hard to prototype scale for an API. We need testing for that.

Until you actually build a working version of the API, you wont get to see all the problems. This is true especially for security issues with the APIs. You have to pay extra attention to possible security risks you may see in production.

Finally, prototypes will help you work out interoperability details with other APIs. But lots of integration and interoperability details are only available once you have a working version of the API.

Working Prototypes

Working or functional prototype is the one that comes closest to the real thing without actually being a production-ready version.

In the API world, working prototypes are usually not very costly to create, given you have proper editing and support tools. Its possible to create more than one prototype or to build several iterations of the same virtual prototype without much added cost. There are powerful tooling for API prototypes in the form of API definition formats like the OpenAPI Specification (OAS).

API Prototyping with OpenAPI

OAS is described as “a standard, programming language-agnostic interface description for REST APIs”. The general goal of OAS is to accurately and comprehensively define an API so that API consumers dont need access to any other information — just the OAS document — in order to understand and successfully use the API.

Defining the API

One of the reasons why OAS is so good at creating API prototypes is that its a rich format for defining the implementation details of APIs. It allows you to outline the URLs your API will publish, along with the inputs API users can send and the outputs those API users can expect to get in return.

You do not need to define every single detail of your production API using your prototype, but OAS is one of the best formats for expressing those details. It makes your prototypes have the potential to be very explicit and eventually very accurate. That can eliminate any surprises when moving from the final prototype into production implementation.

SwaggerHub is an online editor available to create working API prototypes using OpenAPI Specifications. It helps with live editing, generate mock server for prototype testing, and generate technical API documentation. Once you generate these OAS documents, you can use tools like ReDocly to create interactive API documentation as well.