Skip to main content

The Future of API Specifications

· 3 min read

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, Dev Doshi, Mike Amundson and Kin Lane 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...)

alt

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

alt

  • 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

alt

  • Live Demo from the video. The benefits
    • 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

👋 My DMs are Open on Twitter

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

Source Material#