The Future of API Specifications

Aidan Cunniffe 2021-07-21

I'm a big believer that the order you read a set of books can matter more than the books you read. When different ideas and perspectives mix into a savory synapse soup -- good things happen. That was my last 10 days. I've gotten to talk to some amazing people about the history of Swagger/OpenAPI (history matters), why API Specifications matter, and the problems we face building and scaling tools across the wider API Community.

My brain was overloading, so I sat down and did a talk:

Watch the Talk

Big thank you to Matt Trask (opens in a new tab), Dev Doshi (opens in a new tab), Mike Amundson (opens in a new tab) and Kin Lane (opens in a new tab) for the amazing discussions and storytelling. Lucky for everyone reading this, all our conversations are recorded so anyone reading this can try the synapse soup and share their ideas too 🍲.

Key Idea: Make API specs like APIs

  • We value evolvability, approachability, and usability in our APIs, but those principles have not made it into the API specifications themselves.
  • API Specifications are the API for our APIs. Shouldn’t we treat them that way? What would we change if we designed new API specifications like we designed APIs?
  • The current architecture for API specifications complicates the use cases people care most about: design, governance, changelogs, validation, and the emerging patterns/protocols (hypermedia, graphql, grpc...)


  • Explores the conflict and consequences of optimizing for all the above: Human Writable, Human Readable, Machine Readable and Human Writable


  • Proposes a new framing for the problem: make API specs like APIs what if instead of giant YAML files, specs were more like APIs?

    …there are different queries, optimized for each use case

    …and mutations you call when the API changes

    vendors use the API too! with the same reference implementation


  • Live Demo from the video. The benefits (opens in a new tab)

    • one reference implementation, shared by every vendor
    • API specs don't 'break' anymore when we make them better
    • (because of the evolvability above) you could add new protocols and spec features at-will, and future-proofs many of the hard choices
  • Ends with a quick reminder -- we know how to build systems like this, it's what we do with our APIs every day. We are more than capable of making this happen :)

Get Involved

🌊 Want to help bring about this, or another future for API specs? Share the post ✨ Want to explore these ideas together? Join the conversation on GitHub (opens in a new tab)

👋 My DMs are Open on Twitter (opens in a new tab)

Hope this was fun for everyone, keep thinking, get chatting. Cheers.

Source Material

Want to ship a better API?

Optic makes it easy to publish accurate API docs, avoid breaking changes, and improve the design of your APIs.

Try it for free