Capabilities are where my thinking about APIs has landed after fifteen years, and the shift is significant enough that I’ve started dropping the word “API” from the front of it. For years I said “API capability.” Now I just say capability, or business capability, or digital capability — because the emphasis on the API was, I think, holding us back. A capability is a human and machine-readable definition of something you want to accomplish as part of business operations. It could be as simple as scheduling a calendar event or as involved as a segment of a supply chain. It integrates data, functions, and potentially events. And the single most important property: a capability must matter to technical and non-technical stakeholders alike. That last requirement is what makes capabilities fundamentally a governance and business-alignment concept rather than a technical one.
The move from APIs to capabilities reframes the unit of design, and I’ve been building my definition alongside the thinking of people like Daniel Kocot, Christian Posta, Mike Amundsen, and Irakli Nadareishvili. Daniel frames capability thinking as placing the emphasis on what a platform can actually do for its consumers — describing discrete business functions like Ship Order, Process Payment, or Approve Loan rather than exposing granular resources. Instead of POST /refunds, the capability is Process Refund. Christian comes at it from the AI direction, defining a capability as a self-describing, semantically rich declaration of what a system can do, not just how to invoke it. Mike says that when the client is autonomous, your API has to be more than a list of endpoints — it needs to be a menu of possibilities. And Irakli puts the business case most sharply: the first step in breaking the data-centric habit is to stop designing systems as a collection of data services and instead design for business capabilities. They’re all circling the same realization. The endpoint is the wrong unit. The business outcome is the right one.
The defining characteristic of a capability, the one that does all the work, is business alignment. A capability speaks to business outcomes, not system design. POST /refunds is a system detail; Process Refund is a business function that a product manager, a domain expert, an engineer, and a VP can all look at and understand the same way. This is why capabilities have product, engineering, and domain stakeholders attached to them, and why they’re domain-driven — using a common language that aligns engineering with the business. The whole point is to produce an artifact that doesn’t belong solely to the engineers or solely to the business, but lives in the space between them where alignment actually has to happen. I’ve spent years watching organizations fail at exactly this seam, and the capability is my attempt at an object that forces the conversation across it.
I learned the depth of this problem doing API discovery inside enterprises. The first thing I ask any organization I work with is: do you know where all your APIs are? The answer is always no. Development and IT have moved too fast for too long, and the result is that large organizations don’t fully understand their own capabilities — even ones they actively operate, even ones driving live web and mobile applications. Each API represents a single capability, the ability to accomplish a specific task that’s valuable to the business, but without comprehensive discovery, that knowledge stays trapped in individual engineers’ heads. If architects, business leadership, and other stakeholders can’t browse, list, search, and access all the capabilities that exist, then the organization literally cannot articulate what it’s capable of. Developer and IT operations become black holes — sucking up resources while letting very little light out about what’s actually happening inside. That inability to articulate your own capabilities is a governance failure, and it’s nearly universal.
The hard part — and the reason I keep hammering on this — is that everyone is willing to do the technical work of defining a capability, and almost nobody is willing to do the business work. The engineers I sit down with to nail the technical details aren’t always equipped or willing to work through the business details, and the business people aren’t always equipped or willing to work through the technical ones. The person who can do both is a rare beast. So in practice capabilities get the full technical specification and almost no business specification, and the two drift apart over time. That drift is precisely how you manufacture legacy systems and the friction that comes with them. A capability that codifies the technical operation without codifying the business context around it is just a faster route to the same disconnect. Business alignment isn’t a nice-to-have layered on top of the capability — it’s the part most likely to be skipped and the part that determines whether the capability is worth anything.
My full definition of a capability runs to dozens of properties, and I won’t recite all of them, but the shape matters: a capability has intuitive metadata (a title, description, tags) and is business-aligned, domain-driven, and stakeholder-owned. It has clear boundaries and separation of concerns. It’s human-readable and machine-readable, reusable and composable, discoverable through rich metadata, with declared inputs and outputs. It’s executable — an executable unit of business value in a container. And critically for this context, it’s governed, policy-driven, has a maturity model, is monitored, observable, traceable, authenticated, role-based, and secured, with a known lifecycle and a defined total cost of ownership and value exchange. Governance isn’t bolted onto capabilities; it’s woven through the definition. The capability is the abstraction — easily represented by a title, an image, maybe a description and some tags — that lets a business stakeholder engage at their level while the engineering details remain one click deeper. It MUST be accessible to both, or it isn’t a capability.
Capabilities are also where I finally found honest language for control, which is the governance question underneath the business-alignment question. I’ve long used public, partner, and private to describe the APIs we produce and consume, but those words never adequately captured how much control we actually have over our integrations. A capability describes the technical bits and the business bits, but it also describes the human relationships surrounding the integration — which lets us finally have an honest conversation about how much control each stakeholder has or doesn’t have. How much control does your average engineer have over a critical integration? Your average product person? Your average VP? This is bigger than an API contract, which only governs a single API. Real businesses run on derivatives spanning multiple API contracts across multiple providers, with technical and non-technical stakeholders all implicated, and you almost never see an honest conversation about control at that level. Capability thinking is my attempt to shine a light on it and to govern the control we have over the access and data flowing through the endless integrations we depend on to do business every day.
What gives me confidence this is real and not just terminology is how a capability actually comes to life, because it accommodates the messy reality of how organizations work. A capability is JSON or YAML in a Git repository, but usable anywhere, editable in any editor or IDE, with both a developer experience and a user experience so any stakeholder can create and evolve it. It can start as a title and description, or by dragging in an existing OpenAPI, AsyncAPI, MCP server, Postman or Bruno collection, or HAR file. It can come to life from a proxy gathering traffic, a scanner crawling for evidence of data and APIs, an LLM generating a first draft, or by forking an existing capability. It can be greenfield or brownfield, business-initiated or engineering-initiated, manual or automated, headed for production or never leaving simulation. But the through-line is unbreakable: a capability must be equal parts business and engineering for it to remain alive. The moment it becomes purely one or the other, it dies as a capability and reverts to being just an API spec or just a slide.
I’ll be honest that AI is facilitating this conversation — autonomous agents need a menu of well-described capabilities rather than a list of endpoints, and that need is what finally made people care about codifying business capabilities. But I want to be equally clear that AI is not the whole conversation. The reason to embrace capability thinking is the same reason it was always worth doing: as ecosystems expand and automation becomes normal, being able to clearly articulate what your platform can do determines how well it can adapt. Moving from APIs to capabilities is not just a change in terminology — it’s a step toward making digital operations more meaningful, more governable, and more resilient. It’s the closest I’ve come to an object that holds the technical and the business sides of an organization together, governed as a single unit, aligned around a shared outcome. That’s what governance and business alignment have always been trying to achieve. The capability is the artifact that might finally let them.
References
- What Are Your Enterprise API Capabilities?
- Focusing On Digital API Capabilities Over Just Doing APIs
- API Resource, Capabilities, And Experiences
- Will You Or A Vendor Complete The Map Of Your API Resources And Capabilities
- What Is A Capability?
- Capabilities Are About Having An Honest Conversation About Control
- Capabilities Are Everything You Need To Integrate With AI
- How Does A Capability Come To Life?
