Shane O’Connor interviewed me for Off Spec, his newsletter about what the API specifications don’t capture. First published on LinkedIn as Off Spec № 03, July 30, 2026. The questions are Shane’s; the answers are mine.
Off Spec is about what the specifications don’t capture. You’ve spent 20 years turning API specifications into products people actually pay for. What’s the biggest thing about API products that no spec, no product roadmap, and no OKR doc has ever captured?
Capturing the why, the user problem, what the market needs. Seeing the patterns and expressing them in stories is the thing we consistently miss. Today, when it’s easy to just build, that becomes more important than ever. Building the wrong thing that does not get used might be cheap, but it does cost you in reputation in the market. And that’s not infinite.
A good way to remember this is API stands for:
- Application — what is the application or use case for this product? For whom?
- Programming — who’s going to do the programming? What tool and documentation do they need?
- Interface — once you know the other two, now you can design and build an interface.
Not the other way around - API, not IPA, if you will :)
You had a unique vantage point: VP of Product for API Blueprint at Apiary and then for Swagger at SmartBear. Vlad Gorej was on Off Spec № 01 and gave the engineer’s version of why OpenAPI eventually won. From the product-strategy seat, does the story look different? What did you see coming that the engineers couldn’t, and what did they see that you couldn’t?
It was mainly timing and the interop bias of OpenAPI vs API Blueprint’s design bias (we were very early to that, the market was not there yet). Also depth of features: Swagger could describe more things than API Blueprint, and in a code-first world, where the “spec” was generated after the fact for documentation purposes, that was more important than making it a design-first language. As Vladimir noted in № 01, lots of tooling got built around it and that got the flywheel going.
As the head of product I could see the market coalescing around OpenAPI and we decided, as a company, to start supporting it, which meant a huge rewrite. Supporting two API description formats was tough for a small organization, but what it allowed us to do is to crystallize on what was important about the product, which was the design editor with instant rendering of docs and mock. To this date, it has not been surpassed. Our new parsing tools opened the gates for the industry’s first API governance tools, to ensure guidelines and rules were applied across an API portfolio.
One thing I should have pushed more, which engineers loved was the testing harness, Dredd - again to this day I have not seen a more elegant API solution.
Apiary was acquired by Oracle. You lived through what happens when a beloved developer product gets absorbed into an enterprise vendor. What actually changes about product decisions in that transition, and what would you do differently if you were the acquiring exec?
The issue there is that corporate strategy and priorities change continuously. Every turn tests if the acquisition is still core to the business, and more often than not fails that test. That’s why dev tool companies that have stayed independent can still focus on their core mission. Dev tools do not fit portfolios well. So if I were the acquirer, I’d want to make sure the product aligns to the core of the business.
What made this story really interesting is that Oracle still supports Apiary - go check, it’s there. As part of the acquisition we also took over the API Management suite and integrated it with Apiary - so that you could configure gateways directly from either OpenAPI or API Blueprint, a first in the industry. The plot twist was that the API Management suite got deprecated when Oracle moved into the cloud business, while Apiary kept going.
You built Oracle’s first cloud-native API Gateway. Ten years later, do you think the gateway pattern was the right architectural answer, or was it a stopgap the industry has been slowly outgrowing? And if it’s the second, what replaces it?
OCI needed one, no question it was right. Same today, it’s a tool that offloads the non-functional requirements off your services and ensures they are implemented consistently - whether it’s a conventional API Gateway for REST or GraphQL, an MCP Gateway or some flavor of an AI Gateway.
The right way to think about this is the functional vs. non-functional aspect. The former belongs on the service side, never on the gateway. In the industry’s rush to add features, we’ve seen business logic leak to the runtime component, in Thoughtworks’s parlance, “the over-ambitious API gateway”.
You teach API Product Management as its own discipline. What’s the single most consequential thing an API PM has to think about that a normal product PM doesn’t?
It’s a very technical discipline, you must speak the language of developers, understand systems - you own the spec for agents or humans and that of your users - human devs or agents.
In the past, I would often see the product function for APIs be reserved for engineers. With today’s tooling we can train PMs in this, which I believe will enable more teams to deliver good API and MCP, resulting in products that can be used by both humans and agents.
You have a talk called “The Double Life of the API Product Manager.” Where does that double life actually break - is it in the internal politics, the external developer expectations, or somewhere neither PM training nor developer feedback prepares you for?
The double life means you have two sets of customers, one is the devs, human or agents who are building with your API, the other is those they are building for. Ultimately the goal is to help the latter, but perversely they are the ones you know the least. Your customers’ customers if you will.
The make or break is how you get access to them, no logging or monitoring will tell you what they need, if they are finding success. And the only way to get to them is via the first layer, your immediate customers. That’s a lot of work and relationship-building.
As my friend Mike Amundsen says, as an API PM you “solve problems you never thought of for people you never met.” And that’s why we need the Technical Product Management function which I see missing in many organizations.
Developer Experience is the thing everyone claims to prioritise now. From advising Fortune 500s who write it into their strategy decks, what’s the biggest lie companies are telling themselves about DX in 2026?
Everyone thinks they’re doing a great job, so test your beliefs, even the sacred ones. This happens a lot with developer experience and onboarding, for product teams. They never see it through the user’s or the agent’s eyes. They haven’t tested it.
I did a paid DX assessment for a well-known API company whose stated strength was well-designed APIs and mature docs. We measured time-to-first-Hello-World. The main signup path, the one most users would take, was infinite. Not slow, infinite. You literally could not complete it. A secondary path took 5 minutes. Nobody inside knew, because insiders never onboard.
You’ve run API programs at Verisk, Moody’s, and Precisely. Regulated buyers, regulated environments. What does API strategy look like when the consumer of your API has to defend every integration to their own regulator, and how is that different from selling into a Series B startup that just wants to ship?
Repeatability and verifiability, when I’m calculating risk or pricing, I have to be able to go back to that and show how it was done for audits etc. This means that not just the API, but all the underlying data, tables, everything has to be retained with an as-of date attached. That’s a lot of data and a lot to keep track of.
This depends on your domain. One student in my course described needing 10 approvals per API change in fintech - design your strategy for THAT buyer and the Series-B ship-fast buyer becomes easy.
You’re advising Fortune 500 CEOs and AI-forward startups on MCP and AI agent readiness right now. What are the big companies fundamentally missing that the small ones already understand?
Your product must have an agent-friendly headless surface. This means some combination of MCP, API, CLI, Skills and Plugins to let agents use the entire product functionality. There should be no UI-only feature. Don’t rely on agents scraping your UI, they’ll do it but it will be unreliable, costly and not under your control.
When you say “AI agent readiness,” what does that actually look like at the API level? What separates an API that agents can safely use from one that only humans can navigate?
Not just API, but also MCP and to a degree CLI:
The big item is discoverability - agents throw a lot at your interface and it has to respond gracefully. Good naming and descriptions are the first backstop but ultimately it comes down to how good your errors are, how detailed, how they allow the agents to recover.
Oh and idempotency or paging does not work the way you think it would, LLMs can’t count and are prone to hallucination, so you have to be able to deal with that.
I often give the advice, “be boring” for agents, just don’t surprise the model. Do what it expects from its training data, what it’s seen a lot, which may not necessarily be the theoretically correct design.
You advise on both ends of the spectrum. Which end is honestly further ahead on the AI-API question right now - the Fortune 500 with the budget and the compliance teams, or the ten-person startup with no legacy and no permission needed?
Startups by far, they have no baggage to weigh them down. The F500 are not quick to disrupt themselves though there are pockets of innovation everywhere. The difficulty in such large organizations is bringing everyone up to speed and getting them to speak the same language.
Vlad’s answer to “what received wisdom in the API world is wrong” was that specs are mainly for documentation. From the PM seat you sit in, what’s your version? What take would get you booed off the stage at apidays Paris?
That agents read your documentation. Yes, it has to be readable and accessible, but there is no guarantee they will do so. Everyone thinks, just because it’s available, it’ll be crawled and read in its entirety. In reality it gets pulled in just in time, or partially, often not at all. LLMs take shortcuts all the time.
Agents won’t read your specs or docs, and even if they do they may have an old version in their training data they go to. And even if you coerce them to find a fresh version, they’ll just grep through the parts they think are interesting, won’t read the whole thing.
If you think your precious OpenAPI is the most important thing, give Claude Code a spec and tell it to use the API. After it figures it out, ask it how many tries it took - and if it really read your spec. People are always surprised at the result in my live workshops.
What’s a product decision you made - at Apiary, SmartBear, Oracle, or elsewhere - that you’d unmake if you could, and who’d be relieved if you had?
I used to believe that on-prem is the work of the devil. That SaaS was the only way. And there were good reasons for it, one codebase, one deployment, easy to measure and monitor, predictable revenue, all that.
It left a lot of opportunities on the table. I wish I’d found better solutions to this problem because a lot of customers that I wrote off as just backward at the time asked for it. Would have made a lot of sales people (and customers) happy!
You’ve spent 20 years in this. What’s something you wish someone had told you 15 years ago about being an API Product Manager that you now try to tell everyone in your courses?
I wish someone had assured me that “an API is a product” was something I could say in polite company. It was not at all apparent back then. The real product was the UI. APIs were plumbing, something for the unwashed. I arrived at it anyway and spent years evangelizing it because my global customers verified it’s what they want - the ability to integrate into their workflows.
Today more than half of internet traffic is API traffic. The unwashed won.
So now it’s the first thing I tell everyone in my courses: an API is a product. Treat it like one. It is not a by-product that falls out of code. Build it with intent, know who it’s for, and measure whether it delivers.
Lightning round. One word or one line each.
Design-first or code-first?
We no longer code, we give requirements to coding agents. Those better represent what the market needs.
REST, GraphQL, or gRPC in 5 years?
MCP
Most overrated API tool?
An OpenAPI editor
Most underrated?
Your LLM + a Skill
Is OpenAPI already obsolete for agents?
No. It’s the best way we have to describe what API you want built for agents.
Will there be a single winning API standard by 2030, or does the space stay fragmented?
We will be more standards-reliant than ever. When in doubt, check the RFC. It’s what LLMs are trained on.