I’m returning to a healthy vantage point when it comes to API specifications. Like API Evangelist, I have burnt out on the specifications front at various stages. When I get all bitchy and ranty about the people around specs and the specs themselves, it is always a time to step back and assess what matters to me. Other than APIs.json, my role with specs is not about driving the primitives and properties of a spec. It is driving everything that surrounds and goes into specifications–primarily the storytelling, connecting the dots, and motivating the human beans along the way.
I am perpetually fascinated by how people see API specifications, as well as how they don’t see them. Mostly engineering-centered people see them, and mostly non-engineering-centered folks don’t. Of the engineering folks, there are different ways specifications are seen, but I’d say engineers see them in a very boolean way–they either are, or they aren’t. Which could mean they exist or don’t exist. They do what you need or they do not do what you need. They are valuable or they are not. They understand what they do or they do not understand what they do. Where I see API specifications as a living representation of the dimension of APIs that their properties define.
API specifications are living because of the people who create them, move them forward, and negotiate their existence. These people are a unique breed of engineers, and more often than not, these people are very smart, very opinionated, and very much assholes. I consider myself part of this group. I say this affectionately. It is one of the reasons I do not work directly on the primitives and properties of specifications–except for APIs.json. It is easy to burn out being a lightning rod for owning the details of a specification. There are a number of podcasts on my blog with specification founders, owners, and stewards sharing how much of a challenge it can be.
I am thankful for people who step up to create new specifications. Even while living in an XKCD cartoon. I also don’t hesitate to give them a hard time, while simultaneously thanking them for their service. I’m all about telling their story, connecting the dots that matter across the specifications, showcasing the commercial services and open source tooling built on top of specifications, and convincing companies, venture capital, and institutions to fund work on API specifications. I tend to leave the technology of API specifications to the passionate ones who have the vision, and work to bring in the business of what is needed, and help stir the pot and take sides when it comes to the politics of moving API specifications forward.
The most important tool in my API specification toolbox is storytelling. It is one that technical folks overlook and undervalue, and it is essential to growing specifications. Mike Ralphson, who is an icon in the API specification space, publicly said I’ve never once committed a PR to any specification. He said it in a hurtful way, but I received it the way I interpret how engineers always see what I do. They don’t see it. Despite me oftentimes paying their paychecks, bringing in funding, putting on conferences, and telling the story that brings in users. I adore Mike. I adore most engineers. They severely undervalue storytelling and what I do. It’s OK. After 16 years I am very used to it. But just because they don’t see the business and politics of their world doesn’t mean they’ll be left alone to just fiddle with the technical details.
Specifications are living. They represent the human beans who make them and do the work. They represent the community around them. They represent the market they are implemented in. They represent the tooling and services that put them to use. They evolve and change, within each version, but also within each implementation and interpretation by users. I am obsessed with the heartbeat of each API specification right now. I’m fascinated by the relationships between them, even if the human beans haven’t done their due diligence on what the other specs do–yesterday I mapped how nine API specifications point at each other, tracing where OpenAPI, AsyncAPI, JSON Schema, Arazzo, OpenAPI Overlays, Spectral, APIs.json, MCP, and A2A actually reference one another, and where they don’t. I’m fascinated with why folks hate on specs. Why they start new specs. And I’m most interested in how it will take multiple API specifications to bring the interoperability, regulation, and competitive balance we need to move from a teenage tech sector powered by the web to something that begins to grow up and deliver what we need across many different industries, across various regions, and within specific countries, all leveraging the World Wide Web to do what needs to get done.
