API-first vs code-first: the wrong debate for the agent era

The API-first vs code-first debate was largely settled by the early 2020s, and the wrong side won the headlines. API-first — designing the contract before the implementation — became the orthodoxy. Code-first — letting the implementation define the contract — got reframed as legacy. Both camps are now staring at the same problem: agents can't reach most of what their products can do. The methodology you picked in 2018 isn't what's blocking you in 2026.

The original debate, briefly

API-first means you write the API spec (typically OpenAPI, though RAML, AsyncAPI, or Protocol Buffers all fit the same pattern) first, then implement against it. The contract is the source of truth. Tooling, mocks, SDKs, and docs generate from the spec. Teams stay aligned because everyone reads the same file.

Code-first means you write the handlers, decorate them with annotations, and let the framework emit a spec at build time. The code is the source of truth. The spec is a by-product.

For human developers consuming your API, the choice mostly affected developer experience and team workflow. Design-first APIs tended to be more consistent. Code-first APIs tended to ship faster and drift less from what actually ran. Both produced working REST endpoints. Both produced API as a product thinking inside the companies that took it seriously.

That was the debate. It was about how you build the 2% of your product that has an API.

The 2% problem doesn't care which side you picked

Here's what neither camp solved: your APIs expose a fraction of what your product actually does. The UI can do a hundred things. The API exposes a handful of them. That gap exists whether you wrote the spec first or the code first.

API-first teams have cleaner contracts for the surface they chose to expose. Code-first teams have specs that reflect what they actually built. Neither approach generates endpoints for the workflows that live in the UI, the buttons that wire seven services together, the bulk operations the support team uses, the admin functions the product manager built in a sprint three years ago.

Agents need access to all of that. The methodology debate was about the front door. Agents are asking why most of the house is invisible from outside.

API-first development still helps — just not where people think

Where API-first earns its keep in the agent era: the surface you do expose is more likely to be coherent, versioned, and documented. That makes it easier to scan, generate tools from, and maintain as the product changes. A clean spec is genuinely useful — both for human developers and for the connector-generation step that turns API surface into agent tools.

What API-first doesn't do: it doesn't generate the API surface that was never written. If a workflow only exists in the UI, no amount of design-first discipline produces an endpoint for it. The contract you didn't write isn't a contract.

This is the part the methodology evangelists miss. API as a product thinking was a real advance for B2B SaaS. It's also not enough. Treating your API as a product means investing in the surface developers see. Agent-readiness means investing in the surface that doesn't exist yet — the 98% of your product that never made it to the API layer because no human developer asked for it.

What actually differentiates agent-ready products

Stop arguing about how you design the next endpoint. Start asking three questions about your existing product surface:

• Coverage. Of the workflows your UI supports, what percentage have a corresponding API path? For most established SaaS products, the honest answer is uncomfortable.
• Maintenance. When the underlying product changes, what catches the drift before agents start failing? Tests against the spec catch contract drift. Nothing catches the gap between what the API says and what the UI quietly added last quarter.
• Identity. When the agent calls the API, who is it acting as? A service account with admin scope, or the authenticated user with their actual permissions? The methodology debate never touched this. The agent era makes it the central question.

If you're API-first and your coverage is 5%, you have a tidy 5%. If you're code-first and your coverage is 5%, you have a less tidy 5%. The bottleneck is the 95%, not the tidiness.

How Pontil fits

We're not in the API-first vs code-first debate. We sit a layer above it. Pontil is a Tools-as-a-Service platform — we scan existing codebases, generate agent tools that cover the full product surface (not just the API surface), and run them through a managed runtime that executes as the authenticated user.

That means the methodology you picked in 2018 isn't a blocker. If you have a clean OpenAPI spec, we use it. If you don't, we work from the code. Either way, the tools agents need get generated, maintained as the product changes, and run with real per-user permissions. The 2% problem stops being a methodology problem and starts being a surface-coverage problem you can actually fund.

What to do differently

Drop the methodology debate from your agent-readiness conversations. It's a sunk-cost discussion. The relevant question for 2026 isn't whether your existing API was designed well — it's whether the surface agents need actually exists, and how you're going to close the gap without a multi-year rewrite. Audit coverage honestly. Decide whether you're rebuilding the API layer, building bespoke connectors per product, or generating tools from the codebase you already have. That's the real choice. Picking a side in API-first vs code-first was the easy part.