Issue 70

Two recent industry pieces on agent experience (AX) came to the same conclusion: AX cannot be bolted on top of bad API contracts. The thing is, many organisations have nobody accountable for fixing their API contracts – especially for their internal APIs. Here is what the two articles say, and my take on them.

Steps toward great agent experience every API provider can take today: This post by Stainless, an SDK provider, is about agent experience (AX) – which it describes as the process by which agents discover, comprehend, and autonomously operate APIs. AX is important for external APIs because it is a competitive advantage for faster adoption, and AX is important for internal APIs because it saves internal integration time and provides a better dev experience. The foundation of AX is to have API contracts that are the single source of truth for describing your APIs. Your contracts should consistently comply with your style guide, have good examples, and document clear, specific error messages. You should also have comprehensive API references and narrative guide docs in your API catalog and developer portal, and idiomatic, typed SDKs that agents can use. Against this foundation, the article recommends building agent interfaces: MCP servers, agent skills files, and AGENTS.md files. Stainless’ approach to SDKs for agents is SDK code mode, where MCP servers expose just two tools – a documentation search tool and a code execution tool.

My take: I like the point that Stainless makes, that a good agentic experience is based on a solid foundation of high-quality, comprehensive API contracts. This comes back to organisations investing in good-quality API contracts. Many companies invest in this for their external APIs, but not so much for their internal APIs. This is reflective of having no one in charge of the cross-cutting concern of internal API standards and enforcement (an operating model problem). It also shows a lack of policies and CI/CD processes for ensuring contracts are automatically catalogued and updated. Also, I think that agent interfaces should be added where they provide the highest benefit, and iteration is done from there.

API Design Principles for the Agentic Era: This article frames AX as removing friction for agents, just as developer experience (DX) was about removing friction for developers. The article lists 10 recommendations for getting APIs ready for agents:

I will just summarise one of these points – fixing API spec descriptions. The quality of the descriptions on the OpenAPI spec (endpoint/operation and field descriptions) determines which operation the agent picks. And the article makes the point that most OpenAPI specs are bad at descriptions. It makes a strong point that “If your spec is broken for contract testing, it’s broken for agents” because a consumer of the API cannot determine what the API does without running it. The article also mentions one fix for broken descriptions in specs: “Go through your spec field by field. Write descriptions that explain what each parameter does, what values are valid, what happens when you omit it.” I will add that GenAI tools can help with this too.

My take: Just as in the previous article I reviewed, this article shows that the basis of AX is high-quality API specs with good quality descriptions, specific error messages, auth and rate limits designed with the use case in mind. Achieving these outputs is based on a good API design process, and so the design methodology the organisation is using should capture these. Apart from the API design methodology, you should view your API delivery as a system of processes. Map out your organisational API delivery process and look for the reasons why you have had poor quality descriptions in the first place.

In IGT-API Framework terms, AX readiness is the combined output of four capabilities — API Design Enablement, API Discoverability, API Integration Enablement, and API Contract Testing — and the operating-model policies that connect them.

This is a structured canvas for mapping how governance actually works across eight dimensions: decision rights, API classification, lifecycle management, policies, tooling, and more. It's designed to surface the difference between what's documented and what's practised, which is where most governance breaks down. Download here.

I am still running the ‘Beyond the Linter’ study that explores how organisations actually run the people-and-process side of API governance. Take part in the study and share your experience with governance. Also, I will be speaking at API Conference London, on Tuesday May 12th. Hope to see you there.

The Ikenna Consulting Newsletter delivers weekly insights on API governance operating models, helping engineering leaders understand why governance is an operating model problem, not a tooling problem.