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.
Conclusion
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.
Top comments (0)