From Examples to an API description in 2 Minutes

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

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

Conclusion

--

--

Building Tony Stark’s workshop one company at a time. Founder useoptic.com (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

238 Followers

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