API Evangelist Conversation with Tony Tam on the Backstory of Swagger, How OpenAPI Became the Ticket Into AI Infrastructure, and Why the Human Craft of the Contract Endures

My personal history goes way back to the WSDL space, writing SOAP envelopes with old Microsoft tools, and even then I loved that autogenerated clients just worked — the code was horrible, but I didn’t have to look at it. I really got into REST APIs at Wordnik, which I started in 2008. Our CEO wanted to make money off the APIs, but customers wanted clients in Python, PHP, JavaScript, plus documentation, and we had six people. We couldn’t keep up. Literally at three in the morning I emailed one of my engineers — I still have the printout — and said, what if we made an endpoint that returned a description of the API, and from that we generated the docs and clients? He banged out some Java that introspected at startup and returned it. That was the beginning of Swagger. It was completely selfish — pure late-night desperation. Then we realized we could do all kinds of neat stuff with it.

We didn’t know what to name it. We were at Apigee with Marsh Gardner, and Zeke Naranjo — a great designer who’d built a front end on top of it — said, hey, why waddle when you can swagger? That’s where the name came from. Somebody said why don’t we open source it, and I said sure, why not. We opened an IRC channel during the day just to see what would happen. For months people would show up and write nonsense. Then maybe eight months in, someone appeared and said, just so you know, we rolled Swagger out across our whole commerce platform and we’re pushing two billion dollars a day through it — have a nice day — and left. I was like, whoa, what just happened? Eventually we realized the whole thing was backwards: having code generate the description was a terrible workflow. Ed had the idea to make the spec the DSL for the server, so you write the spec and it wires to the server. That was the exact opposite of what we’d built, and it just made sense.

There were two moments where I thought, wow, this is really going to help with AI — before we even called it AI. At a conference there was a Watson demo where someone opened an OpenAPI doc and ordered a pizza, and it guided him through everything. I saw machines weren’t just reading it for simple things — they were interpreting the intent of the document and the APIs and turning that into actions a human could take. The second was Greg Brockman, OpenAI’s president, showing me around 2018 an adapter that read an OpenAPI spec and could respond to all this AI stuff. I thought, this AI stuff is never going to work — and then it became part of their plugin infrastructure. That’s when it hit me: if you have a Swagger or OpenAPI doc describing your API, you are now in the API of the AI infrastructure. As long as it knows how to authenticate, which it can do automatically from the doc, you’re part of the system.

The AI world we’re seeing now could happen without APIs, period. You could argue that at the limit the webpage is the API — that webpages are for robots now, not humans, and half of them are generated by robots anyway. But I still think structure and contracts give even the smartest AIs the best chance at doing a good job. The thing I’m genuinely surprised about is that this didn’t turn into some more efficient binary protocol — but maybe it doesn’t matter, because this was made by humans. It’s artisanal software, and you can read it. If you came up with binary agent protocols and all of this happened now, it probably wouldn’t be friendly to humans — it would just be a blob we’d look at and say, I’m glad something can understand this. So we’re lucky. We got to be in the craft part of computers.

Back compatibility is never going away. It sounds stupid, but it’s always going to be a huge issue, so there’s intrinsic value in spending the extra time. Even with my team now I’m very pro using AI, but I say draw the line right here: design your spec, then let the computer do the rest. Tell it to fill out the implementation from the spec, make the client and the front end speak to the server only through that representation — don’t let it make up all the stuff in between, because it just gets messy. That’s where humans are always going to add the best value. Here’s the gate: this is how you go from one machine to another, you go through this representation, and you let the computers do all the work. That’s where we keep showing our human value.

I don’t see it changing for a long time. After I left SmartBear I ended up at a big company, ready for something new — I’d talked about APIs for ten years and wanted something different — but you can’t get away from it, want to or not. Computers need to talk to computers, and people make the same stupid mistakes without it. I was flabbergasted to see it’s just more of the same, at big scale and slower. There are passionate people who got behind it, released specs for Swift, and internally we use it — the documentation, the payment flows go through it, and people see the value. There’s a lot of protobuf and Google stuff floating around that I think is messier; I don’t love it, but I get it. Honestly, just being able to watch computers talk to each other on their own is enough to make me happy. I wish I got a dime for every download, but I’m super fortunate to have seen the whole thing grow.