From Examples to an API description in 2 Minutes

For new APIs, a design-first workflow is the way to go. Spending time up-front to design a good API contract and get feedback from consumers usually leads to a higher quality API being built.

Many teams are interested in building new APIs design-first but it can be a daunting task get started even with popular API description formats and ecosystems like OpenAPI’s.

But a design-first workflow doesn’t necessarily mean you need to start by learning an API description format. In fact, you can get a lot of the benefits of a design-first workflow without using traditional API descriptions. In this post we’re going to explore why designing APIs by example can be a simpler way to get started.

Benefits of Design-by-Example

  • Example requests come from the perspective of the API consumer. This builds empathy with the consumer and forces you to think more about how the API will be used. This makes the process more accessible to designers and product managers and leads to a better API design.
  • Using example requests lowers the barrier to entry. Examples are concrete and only depend on a basic knowledge of HTTP and JSON, not the additional levels of abstraction that API description formats require.
  • Example requests should align well with scenarios / user stories from your project management process. Often the scenarios get lost in the process of creating the spec, but this way each scenario is documented independently with examples and their relationship is preserved.
  • A library of example requests can be turned into a spec, but a spec can’t usually generate meaningful example requests. The examples can then be used for mock data and are guaranteed to adhere to the spec.

Going from Example Requests → API Spec

Designing-by-examples is much easier than writing a spec by hand, but what do you do from there? One option is to use Optic to build your spec from the examples — Optic knows how to build a spec from real API requests out of the box, and your examples work just as well.

Add an example request/responses on Optic

Click ‘Document new API Request’

Add the path to your spec

Use Optic to document the request and response bodies

That’s it! All you have to do is provide Optic with examples of how you want your API to behave and it will build your spec for you. All of your API consumers can then use Optic to make their local development process more streamlined — any bad requests can be caught immediately. Later on you can add new examples when requirements change, and decide whether to incorporate them into the API design.

We’ve seen many organizations building their own custom OpenAPI spec authoring tools to make it easier for both developers and non-developers to design their APIs according to their organizational guidelines. We hope our example-driven flow is even simpler.


Using examples to drive your API design process builds more user empathy and makes getting started more accessible to all stakeholders. If you want to try designing your API with examples consider giving Optic’s open source tooling a try.




Building Tony Stark’s workshop one company at a time. Founder (YC S18)

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Aidan Cunniffe

Aidan Cunniffe

Building Tony Stark’s workshop one company at a time. Founder (YC S18)

More from Medium

CI/CD for databases: bad idea

CI CD on Mobile application


Postgres: FETCH vs limit

How to recover a MySQL database with .frm and .ibd files