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:
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 🍲.
- 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
- 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 :)
🌊 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)
Hope this was fun for everyone, keep thinking, get chatting. Cheers.
Kin asked an Amazing Question on Twitter (opens in a new tab) "What is @OpenApiSpec"?