Talk transcript

Good afternoon, all. I know I'm standing in between you all and the delicious lunch outside. But stay with me for the next 25 minutes. By the time we are done, you will have a playbook that makes your API work for your developers, pipelines, and AI agents. You'll also have a GitHub repository to fork before the food gets cold.

I want to start with a question. What's harder — getting a developer to their first API call, or getting an AI agent to the right one? Raise your hand if you have measured how long it takes for your engineers to make their first API call of an important API in your organisation. Anyone? I can see one. Nice. Thank you. Keep it up. If you have also measured whether an AI agent can do the same thing without reading your specifications — exactly. That's the gap. And that's the gap we are going to talk about today.

Three consumers. Most of us — myself included — have been designing for one consumer only so far.

I'm Darshit Pandya, Senior Principal Engineer for Platform Stream at Serko, based in Auckland. I've been an AWS Community Builder since 2021, Serverless category — also a HashiCorp and IBM Champion. And as Rachel mentioned, I'm a global speaker. Today I'm in the last leg of my conferences. Feel free to connect with me on Platform Engineering, AI, APIs, and serverless.

Here is what we are going to cover today — four areas. First, the mindset shift, which is the important one. Second, the lifecycle, stage by stage, with a complete lifecycle blueprint. Third, what it looks like in practice — I'll show you the actual scanner you're going to use through the GitHub repository. And finally, a playbook you can fork and use.

The three gaps in API programmes

Let's start with the problem. Three gaps. I see them in almost every API programme I have worked with.

I have sat in post-production incident reviews where a breaking change took down downstream services. No versioning strategy, no consumer strategy — and the worst part, everyone in the room had seen it before. We just never fixed it.

Gap one: no lifecycle. Just launch, ship it, and move on. No design review, no versioning strategy, no deprecation plan. That's the technical depth — just a Swagger page.

Gap two: endpoints without intent. POST /order or GET /users. That works when humans can infer what the API is for. Agents don't infer. They need APIs that describe what they can accomplish, not just what they can call. Most APIs answer: what can I call? Almost none answer: what can I accomplish? That's the intent.

Gap three: no product owner, no roadmap, no metrics, no accountability. Fortune 500 companies are specifically hiring API product managers right now — you can search that up, it's currently in demand. Even New Zealand tech companies are starting to hire dedicated product managers for APIs. Because APIs have consumers, adoption curves, churn, and business issues. Most internal programmes for APIs don't have product managers.

These gaps are connected. Fixing one without the others doesn't hold. Every gap is a compounding cost — developer time spent finding which API to use, how to set it up, how to run it, programme fragility, and agent failure rates.

Why now? The rise of AI agents

So why does this matter now, more than two years before? Traditionally, we always had two consumer types: humans, and in some cases, pipelines. Now there is a third consumer: AI agents.

Agents discover your API at runtime. They parse the schema literally. They may skip your docs entirely — or take those documents so literally that they end up ignoring your schema. Agents need to know before they act whether an operation is safe, mutating, or destructive.

Agent experience (AX) and intent resolution

Two terms worth knowing here. First: DevEx, which means developer experience. A key metric for that is TTFHW (time to first hello world). World-class for time to first hello world is under 15 minutes for your engineers.

Now I want to introduce a new term for API quality from an agent perspective: AX, which means agent experience. Key metric: intent resolution rate. Did the agent pick the right tool? That's important to measure when an agent is calling your APIs.

Same lifecycle, same foundation — but agents need intent to be explicit. Humans can infer it. The fastest growing consumer segment for your API isn't developers — it's agents. Most APIs aren't ready for that. We've been building APIs for years, but now it's time to build for headless. We all live in the terminal. We've built 10x the APIs we needed over the years — maybe 100x. But now you will see 1,000x APIs being built to serve agents.

The redesigned lifecycle: Six stages

Let me show you the redesigned lifecycle for that. Six stages, each one serving all three consumers.

Stage one: the shift that changes everything.

Contract first is table stakes — OpenAPI as your source of truth, linted before a line of code is written. The Spectral rules are in the repository; drop them into your CI today. But contract first describes what the API does. Intent first describes what the API is for. That is the shift.

Eight lines of YAML. The intent field is plain language — what a human reads to understand the API, and what an agent reads to decide whether this API solves the current task. One specification, two audiences. When you design for intent, you are designing for two audiences simultaneously: the human developer who reads it, and the agent who uses it. The intent metadata is what makes your API discoverable and usable by agents, not just humans. Every hour your API takes to understand costs you in developer productivity and agent failure rates.

Security and discovery for three consumer types

Stage two: Build for three trust models.

Three consumer types, three fundamentally different trust models. Agents get short-lived, narrowly scoped tokens — least privilege for that particular task only. An agent orchestrating an order workflow gets tokens scoped to exactly that workflow. It cannot do anything beyond that.

I'm calling this the credential blast radius problem. Agents with broad access create security surface areas that weren't designed for. You scope it, you constrain it. All of this lives at the API gateway level and with your policy engine — not scattered across different services or different consumers. Auth scattered across services means an attack surface you can't see, a maintenance burden you can't scale, and zero visibility into what agents are doing.

Stage three: Discovery.

We have built it securely. Can anyone find it? That's the important one.

For humans, world-class DevEx means under 15 minutes — your engineers should be able to call your API. But for agents, MCP (Model Context Protocol) is the bridge. Your OpenAPI specs, enriched with x-capability metadata, map directly to MCP tool definitions. The intent field becomes a tool description — the thing an agent reads to decide whether this API solves its current task. One catalogue, three discovery paths, same source of truth. The MCP mapping guide is in the repository you're going to get.

Operating, evolving, and retiring APIs

Stage four: Operate it like a product. SLOs (service level objectives) per API product, per consumer tier. With three consumers, measure what consumers feel, not what your infrastructure requires. That's what most teams are missing: consumer type segmentation — human, pipeline, and agent. Traffic patterns and failure cases are completely different for each. An agent that can't resolve intent fails by picking the wrong tool. A human can read the docs and use the right one. Add consumer type labels to every metric at the gateway level — it costs almost nothing, and you will start seeing the agent traffic patterns and developer experience data you've been wanting.

Stage five: Evolve it safely. For humans and pipelines: schema stability, additive evolution as the default, and contract testing in the CI — that's established practice. For agents: intent stability. This is the part most teams haven't thought about yet.

If your capability description says "create a commerce order with payment capture" and you change the behaviour so payment is now a separate call, you haven't broken the schema — but you've broken the intent. An agent that composed its workflow around that intent will now fail silently, meaning more token consumption and more arbitrary outputs. This is where Arazzo comes in. Arazzo is an open standard from OpenAPI that defines sequences of API calls as reusable, portable workflows.

Stage six: Retire. That's a product skill too. Most API programmes I have worked with have zombie APIs — nobody owns them, nobody calls them, and nobody is brave enough to retire them. The deprecation runway means: announce, warn, migrate, and sunset. For agents, capability redirect: when you're sunsetting your APIs, the registry maps the old intent to the new API. Agents self-heal. They don't need a migration guide. And zombie API detection: automated discovery of unowned, zero-traffic APIs. Retire them with data, not with courage. Zombie APIs are infrastructure spend — they're not giving you any return.

The full lifecycle playbook

Now let me pull all six stages into one diagram — the playbook. Six stages, three consumer lanes. One coherent system. Different discovery, different auth, different metrics — but one lifecycle. One catalogue, one source of truth.

The platform engineering layer contains the tools — it's not a strategy. And the product discipline layer is where your developer experience and agent experience metrics live, explicitly, as a first-class measurement concern alongside your lifecycle roadmap. Not as an afterthought. This isn't six separate problems. It's one system.

Everything I've described, you'll find written out in a GitHub repository.

Live scanner demo

So now let's look at what it actually looks like in practice. The scanner is in the GitHub repository — you can put in your API specification file and run it, and you'll see your scorecard.

This example shows a score of 20 out of 100. That doesn't mean it's a bad API — it was designed before intent metadata came onto the scene. But the same API, after applying the x-capability pattern, scores 80 out of 100. DevEx and agent experience both have full marks.

The scanner tells you where the gap is. One command — run it against your own specification or any public API. I tried it with public APIs as well — Stripe, Xero and others — and it starts showing you where the gap is and what you can improve.

And here's what makes this repository different from a framework or just a scanner. You can use it with Kiro or Cursor, and just say "make this API agent ready." The skills and the steering file apply this pattern automatically to your specs — no reading docs, no copy-pasting. The AI coding tool does that work. The repo works with Kiro skills, Claude Code /commands, Cursor rules, and GitHub Copilot instructions as well.

What to measure

Now let's talk about what to measure once you've applied these patterns. Three layers, each one answering a different question.

First, the DevEx metrics. Are your developers succeeding? Time to first hello world is your headline — that's the measurement.

Second, the operational metrics. Is the platform healthy?

Third, business value metrics. This layer gets you your budget. Developer churn. And the most overlooked metric in API programmes: zombie API cost. Every hour of TTFHW friction, multiplied by every consumer, multiplied by every quarter, equals compounding API platform drag.

Now let me be honest about what this costs. Intent metadata is ahead of the standard. x-capability is working, but there's no industry-wide schema yet. You are investing ahead of the curve — agent readiness is early, and essential.

Build multi-consumer, not agent-specific. Think about different kinds of consumers, and let agent readiness be an extension, not a rewrite of your entire APIs. Not every API requires the full lifecycle. The framework is a menu, not a mandate. Start where your internal APIs are bleeding most.

Three things to take home

Here is the playbook — three things you can take home.

One: the lifecycle scorecard. Thirty questions, six stages — score your organisation. Find the weakest stage and start from there.

Two: run the scanner with your existing schema. Then run the fix command — it will update your schema with x-capability placeholder metadata.

Three: fork the repository and open it in your favourite coding agent or coding tool — Kiro, Claude Code, or GitHub Copilot — and call it "make this API agent ready."

One important thing: a great API platform doesn't start with the endpoints. It starts with intent. The lifecycle is the product. The intent is your interface.

Thank you. I'd love to connect with you all — I'll be here after the session. I'd love to chat and hear about your API product strategies.

Talk references

Darshit’s Github repo