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

• Kin asked an Amazing Question on Twitter (opens in a new tab) "What is @OpenApiSpec"?

  • Josh Ponelat (opens in a new tab) had a great answer (opens in a new tab)
  • I threw my hat in the ring too with this response (opens in a new tab)

• API Storytelling with Matt Trask (opens in a new tab)

• API Storytelling with Dev Doshi (opens in a new tab)

• Slides from this talk (opens in a new tab)