These specifications are valuable because they establish shared semantics. Documentation generators, validators, catalogs, CI pipelines and governance tools can all interpret the same description. API products do not have an equivalent foundation. A payment product may combine an HTTP API for initiating payments, an event-driven API for status updates and another interface for managing mandates. Documentation, SDKs, workflows and examples belong to the same product. Yet there is no common, machine-readable way to describe that product itself.

Instead, every API management platform, developer portal or internal catalog builds its own interpretation.

The missing layer is semantic

At first glance, this looks like a portability problem. It is not. Portability is only one consequence of something more fundamental: there is no shared description of what an API product actually is.

Today, API management platforms provide concepts for grouping and publishing APIs. Depending on the platform, these concepts also include subscriptions, quotas, policies, approvals and portal publication. Those capabilities are valuable. The difficulty is that the platform-specific model often becomes the only machine-readable representation of the product.

Every other tool like catalogs, portals, governance pipelines, documentation generators or release automation must either understand that proprietary model or create its own.

Doesn’t APIs.json already solve this?

APIs.json is the most important counterexample and any proposal in this area should start there. It already provides a machine-readable index of APIs together with contracts, documentation, SDKs, workflows and many other related assets. The open question is whether discovery and product semantics are the same thing.

A discovery document can identify related APIs and resources. A product description would additionally express that these interfaces and resources together constitute one versioned product. That relationship becomes explicit and machine-verifiable. This may turn out to be a distinction without a meaningful difference. If a constrained APIs.json profile can express the same semantics, another specification would add little value.

Data product specifications point in a similar direction. They separate the identity of a product from the interfaces and assets associated with it. Their scope is much broader than what would be required here, but the architectural separation is instructive.

A foundation, not another platform

The purpose of such a specification would not be to replace API management platforms. Nor would it attempt to describe pricing, subscriptions, quotas, deployment stages, runtime policies or operational behaviour. Those belong to runtime platforms. The missing foundation is considerably smaller.

It should answer only a handful of questions.

• What is the API product?

• Which APIs belong to it?

• Which supporting resources belong to it?

• Which version of the product does this describe?

Conceptually, the document could be as small as:

oaps: 0.1.0

info:
  ...

apis:
  ...

resources:
  ...

The referenced APIs would remain described by OpenAPI, AsyncAPI, GraphQL SDL or Protocol Buffers. Documentation, workflows, SDKs and examples would remain in their own formats. The product description would simply establish that these artifacts belong together.

Why this matters

Once an API product has a common machine-readable description, different kinds of tooling can build upon it without inventing their own interpretation. A catalog can expose the product. A release pipeline can validate the referenced contracts. Documentation tooling can assemble the associated assets. Governance tooling can evaluate product-level rules. An API management adapter can generate the platform-specific configuration required by IBM API Connect, Apigee, Azure API Management, Kong or Gravitee. Platform-specific models do not disappear. They simply stop being the foundation on which every other tool depends.

The real question

The first discussion should not be about YAML fields. Nor should it be about extension mechanisms. The real question is whether API products represent a distinct semantic concept that deserves a shared machine-readable description.

If the answer is yes, several follow-up questions become interesting.

• Is this fundamentally different from API discovery?

• Could APIs.json express the same semantics?

• What is the smallest useful core?

• Which responsibilities belong in the foundation, and which should remain platform-specific?

Only after those questions have convincing answers does it make sense to design a schema. An API product may need the same thing that OpenAPI and, more recently, mcpdesc provide for their respective domains: a shared, machine-readable foundation that different tools can understand without first agreeing on a particular implementation.

That is the hypothesis worth validating.

This was overdue. For years, API designers had to make an uncomfortable choice: either push more and more query information into the URL, with the usual pain around length, encoding, readability, logging, and operational behavior, or use POST for something that does not create anything, does not change anything, and is really a read. RFC 10008 gives that situation a proper name and a proper method. It deserves the attention it gets.

Still, I am not sure the most interesting question is the method.

The method looks right. The offer remains unclear.

Take a reporting API. A consumer wants revenue numbers by region, product group, customer segment, month, channel, and a few additional filters that depend on internal business logic. The query does not belong into a URL anymore. POST feels semantically lazy. HTTP QUERY looks right. At the HTTP level, it probably is.

But the more important question is what the provider has actually offered. Is this a reporting capability, a flexible analytics interface, or simply a polite way to query internal data structures from the outside? Those are not small variations of the same design. They are different offers, with different expectations, different responsibilities, and different risks.

This is where the current discussion can become too narrow. HTTP QUERY makes the request more honest. It does not make the API promise clearer.

GraphQL and OData are reminders, not rivals.

Complex querying over APIs is not new. GraphQL did not become relevant because people needed another way to spell POST. It became relevant because consumers often need data in shapes that do not follow provider-side resource boundaries.

OData did not become relevant because URLs were too short. It became relevant because enterprises needed conventions for filtering, selecting, expanding, sorting, metadata, and discoverability across structured data APIs.

Both deal with queryability, but not merely as transport. HTTP QUERY sits underneath that. It gives HTTP a better method for a specific class of interactions. Useful, yes. But it does not define the query language, the right amount of consumer freedom, or the safe boundary of the underlying model. That work remains.

A capability is more than query access.

The word I keep coming back to here is capability. Not as another architecture label, but as a discipline question.

If the API offers “monthly revenue insight by region”, the provider can shape that interaction, document the assumptions, test the performance, govern the lifecycle, and support consumers around a recognizable business need. If the API offers “run a flexible query over revenue-related data”, the provider is making a very different promise.

That second promise may still be valid. But it needs different governance, different limits, different observability, probably different pricing, and certainly a different conversation with consumers. Too often we treat these as small design variants. They are not. They are different products hiding behind similar request shapes.

Synchronous means: answer now.

This becomes even more visible in the synchronous case. HTTP QUERY will be tempting because it cleans up a synchronous interaction. A client sends a query. The server returns a result. No awkward POST. No oversized GET. The surface looks better.

For bounded lookups, filtered searches, and well-understood query forms, that can be exactly right. But many queries that look like reads do not behave like simple reads. Reporting, analytics, compliance evidence, and AI-supported evaluation can quickly become expensive, variable, probabilistic, or dependent on multiple sources.

A synchronous API says: I can answer now. That sentence is heavier than it looks. It implies latency expectations, retry behavior, timeout assumptions, and a provider that understands the cost and variability of the query well enough to make the interaction reliable.

HTTP QUERY does not remove any of that. It only gives the interaction a better HTTP shape.

Some queries should not return immediately.

Sometimes HTTP QUERY is enough. Sometimes it is exactly the moment where the better design is not another synchronous request, but a query resource.

In that model, the consumer creates a query, the provider accepts it under known conditions, the status becomes visible, and the result can be retrieved when it is ready. Depending on the context, the result can also be cached, audited, reused, or expired. RFC 10008 itself acknowledges the idea that servers can assign URIs to the query itself or to a specific query result for later use.

This model is less elegant at first glance. It introduces another resource. It asks consumers to deal with state. But that may be the honest model. Not every question deserves the fiction of immediate answerability.

Cleaner semantics do not create a better API.

This is where HTTP QUERY becomes useful, but also misleading. It improves the surface of an interaction. The method is more precise. The intent is less blurry. The old POST workaround becomes less necessary.

That is good engineering work. But a cleaner method can also make a weak design look more deliberate than it is. A vague query interface does not become a well-designed capability because the method is now correct. An unbounded reporting endpoint does not become operationally safe because the request is safe and idempotent. A synchronous interaction does not become reliable because the protocol semantics are better.

HTTP QUERY belongs where the provider can describe the query, bound it, operate it, and support it as part of a clear offer. If that is not possible, the issue is probably not the missing method anymore. It is the design of the API itself.

What remains after RFC 10008.

The useful discussion starts after the method choice. Once the HTTP semantics are clear, the harder design questions become more visible: the query model the interaction needs, the amount of consumer freedom the provider can responsibly allow, the commitment the provider is actually making, and whether the interaction is a capability, a data access shortcut, or a job pretending to be a read.

RFC 10008 fixes an ambiguity in HTTP. That is valuable. But the harder ambiguity often remains in the offer behind the API. And that is not something a new method can standardize away.

In many platform and integration initiatives, the same pattern keeps appearing. Teams invest in API catalogues, developer portals, lifecycle models, governance rules, and better documentation. The landscape becomes more visible. The interfaces become easier to find. The language becomes more disciplined. And yet, something remains unresolved.

Consumers still need to understand too much about internal systems before they can achieve a business outcome. Product teams still duplicate orchestration logic. AI agents and automation tools still struggle to identify what a platform can actually do. API portfolios grow, but the connection to organisational ability remains weak. At first glance, this looks like an API design problem. The endpoints may be too granular. The resources may mirror database structures. The documentation may describe technical access rather than consumer intent.That diagnosis is not wrong. It is just incomplete.

Last September, I wrote about this shift as Capability Thinking: moving from resource-centric interfaces toward descriptions of what a platform can do for its consumers. Instead of exposing only Orders, Customers, or Payments as technical resources, a platform can expose actions such as Ship Order, Validate Customer Identity, or Process Refund. This remains a useful move. It gives consumers a clearer unit of interaction. It reduces accidental coupling. It is also increasingly relevant for workflow automation and AI agents, where intent matters more than access alone. But after working with this idea for longer, I think the more important question sits one level higher. If every team defines capabilities on its own, the result may not be a more coherent platform. It may only be a more polished version of the same fragmentation we already know from API landscapes: duplicated logic, overlapping names, unclear ownership, inconsistent abstractions, and catalogues that look useful but do not guide decisions. The problem is not that teams use the wrong word. The problem is that the word “capability” can remain too close to the interface.

A Capability Is Not an API

In interface design, it is useful to describe a capability as something a platform can do for a consumer. Ship Order. Process Refund. Validate Customer Identity. Approve Loan. But this is only one layer.

Ship Order may be exposed through an API, but the capability behind it is not the API. It includes fulfilment rules, warehouse coordination, carrier integration, exception handling, status updates, operational monitoring, service levels, ownership, and continuous improvement. Some of that is technical. Much of it is organisational. This broader view is central to EDGY capability modelling. A capability is not an application, not a process, not a team, and not an endpoint. It is an outcome-oriented ability of the enterprise. It describes what the organisation must be able to do to realise its purpose. That distinction changes the conversation.

If we say “Customer Onboarding API”, the discussion often moves quickly to endpoints, identity checks, data models, consent flows, and integrations. These are necessary, but they are not enough. If we say “Customer Onboarding capability”, the scope becomes wider. We have to ask what outcome onboarding should produce, who consumes it, what quality expectations exist, which teams contribute, which systems implement parts of it, where the process breaks down, and whether the capability is strategically important or merely operationally necessary.

The API is then no longer the starting point. It becomes one possible expression of a capability. The real question is: what must the organisation be capable of doing, and which APIs help make that ability reusable?

The Risk of Capability Theatre

There is a risk in this discussion that should not be ignored. Capability Thinking can easily become another naming exercise. A team renames Customer Table API to Customer Management Capability. Another team renames POST /refunds to Process Refund. A platform team updates its API catalogue with business-sounding labels, but the underlying services, ownership model, and consumer experience remain unchanged. Nothing structural has changed. The consumers still need to know too much about internal behaviour. Ownership is still unclear. Overlaps remain. Product teams still build around system boundaries. Governance still checks compliance after the fact instead of guiding design decisions before the work starts.

This is capability theatre. It looks like progress because the language has improved. But the operating model remains untouched. A serious capability must have boundaries. It must have outputs. It must be understandable without describing every technical implementation detail. And if it is strategically relevant, it must become part of investment decisions. Otherwise, “capability” becomes another enterprise architecture term that sounds important but changes little.

Capability Maps Change the API Portfolio Conversation

In EDGY capability modelling, a Capability Map is not an API discovery artefact. It is a two-dimensional, one-page, high-level representation of the enterprise’s capabilities. Its purpose is to create a shared view of what the organisation must be able to do, not merely to list technical interfaces. It helps structure conversations about strategy realisation, weak points in operations, governance and accountability, project prioritisation, budgeting, organisational design, and IT application management. For API and integration work, this makes the Capability Map more than an architecture diagram. It becomes a way to decide where API product thinking actually belongs.

Without such a view, API portfolios often grow from local demand. A product needs access to customer data. A partner needs order status. A workflow needs account information. Over time, the organisation gets many interfaces, but not necessarily a coherent platform. A Capability Map shifts the questions.

• Which capabilities are strategically important?

• Which capabilities are duplicated or underperforming?

• Which capabilities are distinctive enough to justify stronger API product management, better contracts, clearer lifecycle ownership, and deliberate developer experience?

This is a different conversation from “which APIs do we have?” It is also different from “which APIs should we publish?” The capability view asks where APIs can support an organisational ability that matters. Some capabilities should be exposed as API products. Some should remain internal. Some may need events rather than request-response APIs. Some may first need process redesign, data quality improvements, or ownership clarification before exposing anything would be responsible. This is where capability modelling and APIOps Cycles can complement each other. Capability modelling helps identify the right problem. APIOps Cycles can help turn that problem into API product work.

APIOps Cycles is a workshop-oriented method for moving API initiatives through product strategy, design, governance, delivery, adoption, and continuous improvement without reducing APIs to technical interface artefacts. Its value in this context is not that it replaces enterprise architecture. Its value is that it gives teams a practical translation layer. EDGY helps to ask: what must the enterprise be able to do, and why does it matter? APIOps Cycles helps to ask: how do we turn the API contribution to that capability into a usable, governable, and improvable product? That distinction matters because API-as-a-Product often remains too narrow when it starts with APIs. Capability modelling gives it a better starting point.

Product Thinking Is Itself a Capability

There is another consequence that is easy to overlook. If an organisation wants APIs to be treated as products, then API product thinking is itself a capability. It requires skills, routines, decision rights, funding logic, governance, feedback loops, metrics, and tools. The problem is not that teams do not “think product” hard enough. Much more often, the organisation has not created the capability that would allow them to do so.

If there is no mechanism for consumer research, no product ownership model, no lifecycle funding, no adoption measurement, no governance that helps with trade-offs, and no link to strategic priorities, the API will remain a technical asset with product language around it. This is why change capabilities matter. Organisations need capabilities that let them adapt: product management, enterprise design, platform governance, API design enablement, portfolio management, and developer experience. These do not directly ship customer orders or approve loans, but they determine whether the organisation can improve the way it builds and exposes such abilities. Without these change capabilities, API-as-a-Product depends on local heroes. With them, it becomes repeatable.

A Capability-First APIOps Cycles Workshop

A practical way to bring this into an IT organisation is to start smaller: one capability, one API challenge, one APIOps Cycles entry point. Pick one capability that is visibly painful or strategically relevant. Customer Onboarding. Partner Integration. Order Fulfilment. Claims Handling. Loan Approval. Identity Verification. Then use the capability as the entry point into APIOps Cycles.

The first step is not to decide which endpoint to build. The first step is to identify the API challenge behind the capability. Is the issue unclear business value? Then the API Product Strategy station is a likely starting point. Is the issue poor consumer experience? Then API Consumer Experience becomes relevant. Is the API already implemented but hard to use, inconsistent, or weakly governed? Then API Audit may be the better entry point. If the capability is blocked by ownership, roles, funding, or decision rights, the Operating Model line is probably more useful than another design workshop. The workshop can stay simple. First, name the capability in business language. What outcome does it produce? Who consumes it? Why does it matter? Second, map the current implementation. Which APIs, events, workflows, data products, applications, teams, and policies currently realise parts of the capability? Where is orchestration duplicated? Where do consumers need to understand internal logic? Third, select the APIOps Cycles entry point and define the next loop. Choose the station or metro line that matches the dominant problem, then use the relevant canvases, checklists, or guidelines to move from diagnosis to design decision, validation, delivery, or improvement. This avoids two common traps. It avoids the enterprise architecture trap of creating a large capability map before anyone sees value. It also avoids the API trap of starting with a single endpoint and calling it product thinking. The useful middle ground is capability-first APIOps Cycles discovery. It gives enough business context to avoid technical tunnel vision. It gives enough method structure to avoid an unbounded architecture discussion. And it gives teams a concrete way to move from organisational ability to API product decisions.

Where Capability Models Meet API Discovery

This also changes how API discovery should be connected to architecture. In their codecentric article “API Discovery with Developer Portals, Catalogs and Marketplaces,” Miriam Greis and Felix Medam make a useful distinction between developer portals, API catalogues, marketplaces, and registries. That distinction matters here because it prevents a common mistake: treating every discovery problem as a catalogue problem. Developer portals support API consumption and onboarding. Registries maintain API artefacts and lifecycle information. Catalogues and marketplaces support discovery for different audiences. None of them should become the master structure for enterprise capabilities.

The capability model belongs in the enterprise architecture context, usually in EAM tooling such as LeanIX or a comparable architecture repository. It answers a different question: what must the organisation be able to do, and how does that ability relate to purpose, products, processes, applications, data, teams, technology, and investment decisions? In the EDGY sense, a capability description should explain what needs to be done to produce its output. It should describe the organisational ability, not the implementation path.

For example:

Capability: Ship Order
Description: Capability of preparing a confirmed order for fulfilment, arranging shipment, and making shipment status available for downstream business activities.

That description stays at the level of what the enterprise must be able to do. It does not yet decide whether the work is realised through an API, an event, a workflow, a warehouse system, manual exception handling, or a combination of all of them. The implementation view can then be linked separately. The capability may be realised by fulfilment processes, warehouse applications, carrier integrations, shipment events, and one or more API products. The API registry can maintain the authoritative API artefacts. The internal API catalogue can make the relevant APIs discoverable for teams. The developer portal can support onboarding and consumption. A marketplace can expose selected APIs for broader ecosystem use. The capability model should connect to these tools, but it should not be absorbed by them. The practical benefit is not another catalogue layer. The benefit is traceability between enterprise architecture and API discovery. When an API is linked to a capability, the organisation can ask better questions. Which capability does this API support? Is the capability strategically important? Is it underperforming? Are several APIs exposing the same ability in different ways? Is the API product improving the capability, or only exposing a system This is the more useful shift: not from better API discovery alone, but from isolated API documentation to architecture-aware API product management.

The Hard Part Is Not the Diagram

Capability maps look neat when they are finished. The real work is rarely neat. People disagree about names. Departments use the same word differently. Managers defend existing boundaries. Application teams describe capabilities according to system ownership. Business teams describe them according to outcomes. Architects may be tempted to resolve this too quickly by creating a clean model that is technically elegant but socially weak. That usually fails. The value of capability modelling is not the diagram as such. It is the negotiation that creates a shared understanding of what belongs together, what should be separated, what should be reused, and what deserves investment. For API organisations, this is particularly relevant. Many API problems are symptoms of unresolved organisational boundaries. Two APIs overlap because two teams interpret the same business capability differently. An API exposes too much internal detail because no one has agreed where the capability boundary should be. A catalogue becomes hard to use because it reflects systems rather than consumer intent. A better diagram helps. But the diagram is not the main intervention. The main intervention is a more precise conversation.

From API Products to Capability-Based Product Thinking

The point is not to turn API catalogues into capability models. Nor is it to create a perfect Capability Map before improving APIs. The point is to connect API product work to the organisational abilities that matter. If a capability remains only an interface-level action, it may improve API design. If it is connected to enterprise capability modelling, it can also influence investment, ownership, governance, and product decisions.

The next maturity step is not simply moving from APIs to capabilities. It is moving from isolated API products to capability-based product thinking.

The result is not necessarily worse engineers. It is a system where it becomes much easier to produce software without fully understanding it.

AI hides complexity, especially where it matters most

That shift changes the role of enabling teams as defined in Team Topologies in a fundamental way. In the original model, enabling teams exist to help stream aligned teams acquire better ways of working. They are temporary, focused, and explicitly designed to reduce cognitive load by guiding teams through unfamiliar terrain. They do not own delivery. They do not become permanent dependencies. Their value lies in accelerating learning and then stepping back. With AI, the nature of what teams need to learn changes. The challenge is no longer just adopting a tool or a framework. It is developing the judgment to work effectively with a system that produces plausible but not always correct output. It is about maintaining strong engineering practices in an environment where the feedback loop between action and understanding has been weakened.

AI does not remove complexity. It hides it. Generated code often looks right. It compiles, it runs, it passes basic tests. But under stress, under scale, or in the messy reality of distributed systems, its shortcomings emerge. Integration heavy environments are particularly vulnerable. This is where correctness depends not on isolated logic, but on contracts, timing, failure handling, and consistency across boundaries.

Here, AI tends to underperform in predictable ways. It glosses over idempotency. It simplifies retry logic. It assumes ideal network conditions. It produces APIs that work in isolation but drift when evolved. It handles the happy path elegantly and leaves the failure modes underspecified. None of this is surprising. These are areas where correctness depends on experience and careful reasoning. AI does not carry that experience in a way that aligns with your system’s specific constraints. This is where enabling teams become indispensable, not as gatekeepers, but as guides who help teams see what is no longer obvious.

From coaching to curating engineering practices

The most effective enabling teams are not focused on getting teams to use AI. That is happening regardless. Their focus is on how AI is used, and more importantly, how its output is interpreted. They teach teams to treat AI as a collaborator rather than an authority. That means questioning outputs instead of accepting them, asking for assumptions rather than just solutions, and deliberately exploring failure scenarios instead of stopping at the first working implementation. It means reintroducing the kinds of questions that friction used to force naturally. What happens when this call is retried. What guarantees do we have about ordering. Is this change backward compatible for consumers we do not control. How does this behave under partial failure.

These are not new questions. What has changed is that AI no longer forces you to ask them. Beyond coaching, enabling teams play a crucial role in turning good engineering practices into something reusable. In an AI driven environment, individual developers will inevitably create their own prompts, scripts, and workflows. Left unmanaged, this becomes a new form of fragmentation. Practices diverge. Assumptions go unchallenged. Knowledge remains local and eventually decays. The opportunity is to transform these ad hoc approaches into shared ways of working. This is where the idea of skills becomes powerful. A skill is not just a clever prompt. It is a structured expression of how work should be done within the context of the organization. It encodes intent, constraints, validation steps, and expected outcomes. It reflects not just what to do, but how to think about the problem.

A well designed skill for reviewing an API contract, for example, does more than check syntax. It guides the reviewer through compatibility concerns, naming conventions, error handling, and versioning risks. It embeds the organization’s standards into a reusable form that can be applied consistently across teams. In this way, enabling teams scale their influence without becoming a bottleneck. They move from direct intervention to curating effective engineering practices.

Agents need boundaries, not enthusiasm

Agents extend this idea further, but they also introduce new risks. When workflows become automated across multiple steps, the potential for silent errors increases. An agent that generates code, modifies it, and integrates it into a system can amplify both good and bad practices at scale. The role of the enabling team here is not to prevent the use of agents, but to define their boundaries. What are they allowed to do. Where is human oversight required. Which domains are too sensitive to delegate. How are their actions observed and validated. The principle is straightforward but often overlooked. Agents can assist decision making, but they cannot replace engineering judgment.

Without this kind of guidance, organizations drift into a fragmented landscape. Teams develop their own ways of working with AI. Some become highly effective, others accumulate hidden risks. Integration patterns diverge. Architectural consistency erodes. Over time, the system becomes harder to reason about, even as delivery appears to accelerate. This is the paradox of AI in software engineering. It increases the speed of change precisely in the areas where mistakes are hardest to detect and most expensive to fix.

Enabling teams, in the sense defined by Team Topologies, are one of the few mechanisms that can counterbalance this effect. They reconnect speed with understanding. They ensure that what is produced quickly can still be trusted, evolved, and operated. Their role is no longer just to help teams adopt better practices. It is to preserve the conditions under which good engineering remains possible. The organizations that get this right will not be the ones that use AI most aggressively. They will be the ones that integrate it most thoughtfully into how teams learn, share knowledge, and maintain discipline.

In the end, AI does not replace engineering fundamentals. It removes the pressure that once enforced them. Enabling teams are what reintroduce that pressure in a way that is deliberate, scalable, and aligned with how modern systems are built.

They are not a supporting function anymore. They are becoming the backbone of AI native engineering.

In practice, this assumption rarely holds. Instead of clarity, it produces APIs that mirror internal structures, expose domain complexity, and are difficult to evolve. The problem is not Domain-Driven Design itself, but the expectation that it should directly inform how systems are consumed.

Separating Concerns: Domain, Capability, and API

In a previous article

the argument was made that APIs are not the system. They are an expression of what a system does. This distinction is critical, because it shifts the focus away from implementation and toward responsibility. If APIs are expressions, then the question becomes what exactly they are expressing.

To answer that, it helps to separate three distinct concerns that are often conflated. Domain-Driven Design is concerned with meaning. It helps structure the understanding of a complex business domain, define boundaries of consistency, and align language between stakeholders and engineers. Capability thinking is concerned with responsibility. It defines what a system actually provides in terms of outcomes. API Design First is concerned with interaction. It defines how those outcomes are exposed and consumed under conditions of independent evolution.

These concerns are related, but they are not interchangeable. Problems begin when they are collapsed into a single layer, usually by assuming that domain boundaries should directly translate into APIs.

The Real Problem: Model Leakage and API Sprawl

The typical chain of reasoning looks straightforward. A bounded context is identified. That context becomes a service. The service exposes an API. The domain model becomes the API schema. Aggregates turn into resources, entities into representations, and domain language becomes the contract. The result is an API surface that reflects how the system is built rather than what it offers.

This is where API sprawl begins. It is not primarily a scaling problem or a matter of too many services. It is a modeling leakage problem. Internal structure is exposed as external contract. Consumers are forced to understand domain concepts that were never meant for them. Workflows are fragmented across multiple endpoints. Orchestration shifts to the consumer side. What looks like a well-structured domain internally turns into a confusing interaction model externally.

The root cause is not Domain-Driven Design, but the absence of an intermediate abstraction. Capability thinking fills that gap. A capability describes a cohesive unit of business functionality that delivers a meaningful outcome, independent of how it is implemented. It is neither as fluid as a domain model nor as rigid as an API contract. It provides a stable anchor between the two.

Domains evolve as understanding deepens. Concepts are refined, boundaries are adjusted, and models change over time. APIs, on the other hand, must remain stable because they are consumed across independent lifecycles. Capabilities sit between these forces. They are stable enough to serve as a foundation for APIs, yet meaningful enough to remain grounded in the business.

Designing for Outcomes: Capabilities as the Anchor

When APIs are designed around capabilities rather than domains, the interaction model shifts. Instead of exposing internal structures, the system exposes outcomes. Instead of requiring consumers to navigate aggregates and entities, it provides entry points aligned with real use cases. The API surface becomes smaller, more coherent, and easier to evolve.

This also clarifies a common misconception about internal and external APIs. The distinction is often framed in terms of network boundaries or visibility, but that is not what matters. The relevant factor is whether components evolve together or independently. The moment independent evolution is introduced, explicit contracts become necessary. Capability boundaries often align with these points of independence, which is why APIs tend to emerge naturally around them regardless of whether they are labeled internal or external.

Revisiting Domain-Driven Design in this context leads to a more precise understanding of its role. DDD is essential for making sense of the system. It defines the language, the invariants, and the structure of the domain. It should inform how the system is built internally. What it should not do is dictate how the system is exposed. Treating domain models as APIs exports internal complexity and couples consumers to concepts that are still evolving.

A more effective approach is to let each discipline operate on its intended level. Domain-Driven Design explains the system. Capability thinking defines what the system is responsible for. API Design First determines how that responsibility is made accessible. The boundaries between these layers are not weaknesses. They are where architectural decisions actually take shape.

The practical implication is straightforward. Start by identifying capabilities rather than endpoints. Focus on the outcomes the system must provide. Use domain modeling to ensure those capabilities are implemented correctly. Then design APIs that make those capabilities usable and stable over time. Accept that translation between these layers is not overhead but necessary work to prevent leakage and coupling.

The shift from domains to capabilities is not about replacing one paradigm with another. It is about recognizing that different problems require different abstractions. Domains capture meaning. Capabilities capture intent. APIs capture interaction. When these are aligned deliberately rather than conflated, systems become easier to understand, easier to use, and easier to evolve.

The conclusion from the earlier article still holds. APIs are not the system. They are an expression of what the system does. The extension of that idea is equally important. What they should express is not the domain itself, but the capabilities derived from it.

For years, ArchiMate 3.x, culminating in version 3.2, has provided a stable and widely adopted foundation for modeling enterprises. It refined the language, improved consistency, and strengthened alignment with frameworks like TOGAF. It gave us a shared vocabulary across business, application, and technology layers. But in doing so, it also revealed its own limitations. The layered paradigm, while elegant in theory, often feels artificial in practice. Real systems do not behave in layers. They behave as interconnected, evolving networks.

ArchiMate 3.2 represents the maturity of that paradigm. It is polished, consistent, and reliable. Yet many practitioners recognize the friction it creates. Models become complex to the point of inaccessibility. Stakeholders outside architecture struggle to engage with them. Concepts are duplicated across layers, and the cognitive load remains high. In many organizations, ArchiMate risks becoming a language spoken only by architects, rather than a medium for shared understanding.

From Layers to a Common Domain

This is precisely where ArchiMate Next enters the conversation. Instead of continuing incremental refinement, it challenges the foundation itself. The most significant shift is the move away from strict layering toward a unified conceptual space, often described as a common domain. This is not just a structural adjustment. It is a philosophical one. It replaces hierarchical decomposition with systemic thinking. It acknowledges that modern enterprises are not stacks but networks of capabilities, services, actors, and technologies that continuously interact.

This shift strongly resonates with an idea I explored in my Architectural Bytes post from September 2nd last year,

In that piece, I argued that APIs are not the fundamental unit of architecture. Capabilities are. APIs expose, but capabilities endure. They represent what an enterprise can actually do, independent of how that ability is implemented or accessed.

Seen through that lens, ArchiMate 3.2’s layered structure tends to fragment capabilities across business, application, and technology representations. The same capability is modeled multiple times, in different abstractions, creating both redundancy and cognitive overhead. ArchiMate Next, with its move toward a common domain, implicitly aligns with capability thinking. It creates the conditions to model capabilities as first-class, cross-cutting constructs rather than artifacts confined to a single layer.

This is more than a modeling convenience. It is a shift in how we conceptualize the enterprise. Instead of asking which layer something belongs to, we ask what capability is being realized and how it manifests across the system.

Simplicity Versus Expressiveness

One of the most striking aspects of ArchiMate Next is its ambition to radically simplify the language. This is not simplification for its own sake. It is a response to a real and persistent problem: enterprise architecture models are too often too complex to be useful. By reducing redundancy, minimizing concept overlap, and improving visual clarity, ArchiMate Next aims to make models more accessible and more communicative. The implicit goal is to shift modeling from an exercise in precision to an instrument of understanding.

This raises an important question. Does simplification come at the cost of rigor? There is a legitimate concern that reducing the number of concepts or abstracting away distinctions could weaken the expressive power of the language. At the same time, one could argue that a model that cannot be understood is already failing its purpose. The tension between precision and usability is not new in enterprise architecture, but ArchiMate Next brings it to the forefront in a way that demands a clear position.

Another notable shift is the tighter integration of strategy, intent, and execution. In ArchiMate 3.2, these concerns are present but often separated through extensions and layers. In practice, this can reinforce silos between strategic thinking and operational reality. ArchiMate Next appears to move toward a model where purpose, capability, and implementation are more directly connected. This further reinforces capability thinking as a unifying perspective, linking why something exists with how it is realized.

What This Means for Architects and Organizations

For practitioners, this implies a change in role. The enterprise architect is no longer primarily a modeler of structures but increasingly a facilitator of shared understanding across domains. Mastery of notation becomes less important than the ability to frame complex systems in ways that stakeholders can engage with. Systems thinking, communication, and abstraction become the critical skills.

Capability thinking becomes particularly relevant here. If capabilities are the stable anchor in a continuously evolving system, then architecture work shifts toward identifying, refining, and communicating those capabilities clearly. The model becomes a means to express capability realization rather than an end in itself.

For organizations, the potential upside is significant. A simpler, more coherent modeling approach could enable broader participation, better alignment between strategy and execution, and faster adaptation to change. However, the transition will not be trivial. Existing models, tooling, and practices are deeply rooted in the 3.x paradigm. A period of coexistence is inevitable, and the migration path is still unclear.

It is also important to recognize that ArchiMate Next is still a snapshot, not a finalized standard. Its concepts will evolve, and its success will depend on community feedback, tooling support, and real-world adoption. What we are seeing now is not the end state, but the direction of travel.

From a broader perspective, the contrast between ArchiMate 3.2 and ArchiMate Next can be framed as the difference between optimizing a mature paradigm and initiating a new one. Version 3.2 represents the peak of layered enterprise architecture modeling. ArchiMate Next signals a shift toward modeling enterprise complexity as it actually exists: interconnected, dynamic, and increasingly difficult to decompose.

The real question is not whether ArchiMate Next is better than 3.2 in a strict sense. The question is whether it is more relevant to the challenges we face today. If enterprise architecture is to remain meaningful in an era of platforms, ecosystems, and AI-driven systems, it must evolve beyond the constraints of its original abstractions.

ArchiMate Next is an early but decisive step in that direction. And if we take capability thinking seriously, as argued in “From APIs to Capabilities,” then this shift is not just welcome, it is necessary. The prudent approach is not to wait for full standardization, but to start engaging with the ideas now. Experiment with the concepts, challenge the assumptions, and contribute to the conversation. Because if this shift succeeds, it will not just change how we model enterprises. It will change how we understand them.

Centralized Expertise Is Not a Strategy

When AI is introduced, complexity increases. Probabilistic behavior replaces deterministic logic. Evaluation becomes continuous rather than static. Cost behavior becomes dynamic. Risk exposure becomes harder to reason about. The natural reaction is to centralize expertise.

A dedicated AI team is formed. It prototypes, defines patterns, supports product teams, and becomes the institutional owner of intelligence. At first, this accelerates learning. Concentrated expertise reduces friction. Early use cases become possible. But over time, a structural problem emerges.

AI becomes something “they” handle. Product teams consume outputs rather than owning implications. Contracts thin out because consumers no longer fully understand the producing logic. Risk becomes concentrated in a small group of specialists. When that group is overloaded or misaligned, the entire system slows down. Centralized expertise is useful for exploration. It is insufficient for sustainability.

If AI supports real business decisions, responsibility cannot remain isolated. The engineering discipline required to operate it must be distributed.

Enablement Is Transfer, Not Service

This is why enablement matters, but only if it is understood correctly. Enablement is not a permanent internal service that absorbs complexity on behalf of others. It is a mechanism for transferring competence. It exists to reduce dependency over time, not to institutionalize it. If delivery teams cannot reason about how AI affects their contracts, their domain boundaries, and their risk exposure, then the organization has not matured. It has merely reorganized responsibility.

AI changes the nature of systems. It introduces behavioral variability. It shifts where guarantees live. It alters how meaning is encoded into contracts. These implications cannot remain specialist knowledge. They must become normal engineering practice. Sustainability requires shared discipline.

Governance Must Live Inside the System

Even with distributed competence, one challenge remains. AI systems evolve. Models drift. Thresholds change. Prompts are adjusted. Data distributions shift. Documentation and approval boards cannot keep pace with this dynamism. Traditional governance mechanisms assume relatively stable systems. AI invalidates that assumption. If governance exists primarily in documents, reviews, and ex post approvals, it will always lag behind system behavior. And when governance lags, risk accumulates invisibly.

Governance must therefore become an operational property of the system itself. Decision thresholds must be explicit and versioned at the contract level. Behavioral changes must be traceable. Evaluation processes must be reproducible. Observability must capture semantic context, not just technical metrics. Risk categories must translate into concrete engineering constraints. Governance cannot merely describe the system. It must shape how the system behaves. When governance is embedded into contracts, pipelines, and platforms, it stops being a brake and becomes a stabilizer. It reduces ambiguity rather than adding friction. It allows change without chaos.

Discipline Determines Strategy

AI transformation rarely fails because a model underperforms. It fails because the surrounding engineering system cannot repeatedly absorb uncertainty in a controlled way. Structure without meaning is brittle. Meaning without alignment is unstable. Alignment without distributed discipline is temporary.

Sustainable business capability emerges when contracts are explicit, semantics are coherent, boundaries are enforced through architecture, competence is distributed rather than centralized, and governance is embedded rather than attached. AI does not become strategic when it becomes intelligent. It becomes strategic when it becomes dependable.

And dependability is engineered.

You can have technically stable interfaces and still automate confusion. You can version endpoints correctly and still break meaning. You can design clean service boundaries and still expose inconsistent concepts. This is where a deeper issue appears. Many organizations do not primarily struggle with tooling. They struggle with a partial and sometimes superficial understanding of modern software design principles, particularly Domain-Driven Design.

Tactical Modeling Without Strategic Boundaries

It is common to hear that a team “does DDD.” In practice, this often means tactical DDD. Aggregates are modeled. Entities are introduced. Repositories are defined. Internally, code becomes cleaner and domain concepts more visible. That work is valuable. But it is not strategic DDD.

Strategic DDD is about boundaries. It is about defining where language changes meaning. It is about context mapping. It is about clarifying ownership and making integration explicit. It forces the uncomfortable question of whether two teams really mean the same thing when they use the same word.

When tactical modeling happens without strategic boundary clarity, something subtle emerges. Locally, clarity improves. Globally, ambiguity persists. Services become elegant inside and vague at the edges. Concepts are well understood within a team but poorly encoded in contracts. Integration becomes dependent on shared assumptions rather than explicit agreements.

As long as systems remain largely deterministic, this gap can remain manageable. AI changes that. AI consumes semantics. It operates on definitions, categories, thresholds, and policies. It does not resolve conceptual ambiguity. It scales it.

When Meaning Does Not Survive the Contract

Consider a term like “risk.” In one domain, risk may refer to regulatory exposure. In another, fraud probability. In another, customer churn likelihood. Each meaning can be valid within its bounded context. Strategic DDD allows this diversity as long as the boundaries are explicit and context mapping is disciplined. The problem begins when these distinctions are not reflected in contracts.

If a contract exposes a generic risk score without encoding its context, downstream systems will interpret it through their own semantic lens. A change in model logic may not alter the payload shape at all, but it may fundamentally change the meaning of the output. From a structural perspective, nothing broke. From a business perspective, everything did.

This is why precision matters. We do not version services. We version contracts. And contracts are not only schemas. They encode meaning, guarantees, and behavioral expectations.

If the interpretation of a confidence score changes, that is a contract change even if the JSON structure remains untouched. If a recommendation shifts from advisory to binding in downstream workflows, that is a contract change even if no endpoint changes. AI makes this visible because behavioral evolution becomes frequent and subtle.

When versioning is reduced to endpoint paths or implementation artifacts, semantic drift becomes invisible. Strategic DDD must therefore extend beyond modeling workshops and influence contract design directly. Boundaries must not only exist in diagrams or codebases. They must be operationalized at integration points. Context mapping must be expressed through explicit, evolvable contracts. Without this alignment, bounded contexts are theoretical while system behavior becomes entangled.

Architecture as Alignment, Not Decoration

This is where enterprise architecture must play a different role than it often does. Architecture cannot be limited to documentation or review cycles. It must ensure that strategic boundaries are reflected in contracts and integration patterns. It must prevent meaning and structure from drifting apart. It must clarify where decisions are local and where they require coordination.

When architecture acts as alignment rather than decoration, semantics and structure reinforce each other instead of drifting. AI transformation does not fail because organizations lack intelligence. It fails because meaning, contracts, and boundaries are not synchronized. Disciplined contracts provide structural stability. Strategic Domain-Driven Design provides conceptual clarity. Architecture ensures that both remain aligned over time.

If any of these elements are superficial, AI will expose it.

In the final part of this series, we will examine how this alignment becomes sustainable across the organization, and why distributed engineering discipline and embedded governance determine whether AI supports durable business value or recurring experimentation.

Across the next essays, I will explore why API design first is a prerequisite for meaningful AI introduction, why domain driven design is necessary but not sufficient, and why enterprise architecture must evolve from gatekeeping into enablement if organizations want AI to become a sustainable capability rather than an expensive source of entropy.

Without API Discipline, There Is No Meaningful AI

AI Fails Where Contracts Are Weak

AI transformation rarely fails at models. It fails where system contracts are implicit, unstable, or poorly owned.

Many organizations approach AI introduction as a capability question. Which model should we use? Should we build or buy? Do we fine tune or prompt engineer? These are valid questions, but they are second order. The first order question is more uncomfortable: can your system absorb probabilistic behavior without collapsing into ambiguity?

The moment AI enters a system, ambiguity increases. Outputs are no longer strictly deterministic. Confidence levels matter. Explanations matter. Fallback paths matter. Human review paths matter. Costs fluctuate. Latency patterns shift. Security risks expand. Data provenance becomes critical.

If your interfaces are already loosely defined, AI does not integrate into them cleanly. It exposes their weakness.

When APIs are treated as implementation details rather than contracts, teams rely on assumptions instead of guarantees. Fields are added without versioning. Error semantics are inconsistent. Ownership is unclear. Observability is partial. Deprecation is informal. These issues are manageable in deterministic systems because behavior is predictable. With AI in the loop, they become systemic risks.

A probabilistic component sitting on top of unstable contracts is not innovation. It is entropy.

Meaningful AI introduction requires that system boundaries are explicit, stable, and evolvable. Without that, AI becomes a black box attached to a gray box.

API Design First Is Not About Tooling

API discipline is often misunderstood as a tooling preference. Write an OpenAPI specification first. Generate stubs. Document endpoints. While these practices are useful, they are not the essence of API design first.

API design first is an architectural stance. It means that interfaces are treated as first class organizational agreements. It means that contracts are designed intentionally before implementation, reviewed from the perspective of consumers, and evolved with discipline.

An API is not a technical endpoint. It is a promise.

It is a promise about semantics. What does this operation mean in the domain? What guarantees does it provide? What does failure mean? What is considered a breaking change? What is stable, and what is experimental? How will consumers know when something is being deprecated? Who owns this interface long term?

In the context of AI, these questions become more urgent. If an AI component produces classifications, what does a classification represent? Is it advisory or binding? What does a confidence score mean? What happens below a threshold? Is abstention part of the contract? Is explainability exposed through the interface or treated as an internal detail?

If these aspects are not encoded into the contract, they become tribal knowledge. Tribal knowledge does not scale. It does not survive team changes. It does not withstand audits. And it does not provide a stable foundation for AI capabilities that are expected to influence decisions, customer interactions, or regulatory outcomes.

Design first forces these conversations to happen before code solidifies assumptions. It creates a space where semantics, evolution, and responsibility are discussed deliberately rather than discovered through incidents.

This is not bureaucracy. It is risk management through clarity.

Contracts Are the Real Prerequisite for AI

Before cognition comes contracts. Before intelligence comes integration.

AI capabilities depend on structured inputs and predictable interaction patterns. They require clean separation between domains. They require event flows that can be traced. They require APIs that do not silently change shape. They require consistent error handling and authentication mechanisms. They require observability that extends beyond infrastructure into behavior.

If these elements are weak, AI introduction becomes fragile. Teams build adapters around inconsistencies. They compensate for missing guarantees with defensive coding. They introduce additional layers of translation to stabilize unstable boundaries. Complexity grows, not because AI is inherently complex, but because the underlying contracts are not trustworthy.

Organizations often attempt to mitigate this by centralizing AI expertise. They create innovation labs or AI platforms that abstract away the mess. In the short term, this can work. In the long term, it increases the gap between experimentation and production reality. The platform becomes a buffer between clean demos and messy systems. Eventually, that buffer collapses under integration pressure.

The alternative is less glamorous but more durable. Treat APIs as products. Make contracts explicit. Define ownership clearly. Enforce versioning policies. Build observability into the interface layer, not as an afterthought. Make it easier to evolve interfaces safely than to change them casually.

When contracts are stable and intentional, AI can be introduced incrementally. A new probabilistic capability can sit behind a well defined interface. Consumers can adapt gradually. Governance can be embedded into the interaction model. Risk can be bounded.

When contracts are weak, every AI integration becomes a structural gamble.

If AI transformation is to be more than experimentation, it must begin with API discipline. Not as a documentation exercise, but as an organizational commitment to explicit, evolvable, and owned system boundaries.

In the next part, we will examine how domain driven design fits into this picture and why semantics without disciplined interfaces are not enough to make AI capabilities sustainable.

The end of the year usually invites conclusions. Summaries of what mattered and predictions about what comes next. In architecture and software, those conclusions often appear as trend lists and confident statements about the future.

This year, that framing feels less convincing.

2025 was not short on new ideas or bold claims. If anything, it produced more narratives about acceleration, intelligence, and transformation than most teams could realistically absorb. Yet many of the struggles I encountered had little to do with missing innovation. They came from familiar places. Unclear ownership. Mismatched expectations. Methods applied by name rather than by intent.

That is why this is not a post about what will define the next year. It is a pause to look at what already exists and how easily its value is lost when we stop being deliberate.

From frameworks to fluency

There is no shortage of methodologies. Domain Driven Design, Team Topologies, platform thinking, event driven architectures, governance frameworks, API related methods, and newer practices like Spec Driven Development have all reached a level of maturity where novelty is no longer the problem.

Yet in practice, they are often reduced to labels. Platform thinking becomes a rebranding exercise. Team Topologies turns into an org chart discussion. Spec Driven Development, an approach that treats specifications as first class artifacts guiding both humans and AI, is discussed as a trend without fully engaging with what it implies for alignment, ownership, and upstream decision making.

This is not a tooling issue. It is a fluency issue.

Enablement means choosing methods consciously and accepting their implications, not just their terminology. Domain Driven Design is a commitment to real domain ownership and long lived responsibility, not a naming exercise for microservices. Team Topologies forces organizations to confront how teams actually interact and where cognitive load is ignored, not to redraw reporting lines. Platform thinking requires sustained investment in enablement and product thinking, not a convenient label for shared infrastructure. Event driven architectures demand discipline around contracts, evolution, and operational accountability, not just looser coupling through messaging. Governance frameworks only create value when they coordinate decisions early, not when they are used to justify control after the fact. API related methods surface hard questions about value, consumers, and lifecycle that cannot be automated away or delegated to tools. The same applies to Spec Driven Development. Its value emerges when teams understand how specifications shape shared understanding, feedback loops, and long term maintenance rather than treating them as another input for code generation.

Literacy before acceleration

AI made this gap impossible to ignore in 2025. Automation lowered the cost of producing code, specifications, policies, and even architectural drafts. What it did not lower was the cost of misunderstanding.

Without a shared baseline, acceleration amplifies inconsistency. Teams move faster, but in different directions. Architectural debt grows quietly, not because teams act irresponsibly, but because they act without a common frame of reference.

This is where many API and platform initiatives struggle. Delivery scales before organizations learn how to reason consistently about interfaces, ownership, lifecycle, and value. Methodologies can reveal these gaps, but only when they are used as thinking tools rather than execution recipes.

Governance as coordination, not correction

One of the more interesting shifts in 2025 was the return of governance to architectural conversations. Not as bureaucracy, but as a response to real friction.

At scale, autonomy without coordination collapses into chaos. Governance, when done well, is not about enforcing rules after the fact. It is about making expectations explicit early enough so teams can make informed decisions.

Architecture becomes relevant again when it focuses on enabling alignment rather than policing compliance.

Methodologies are not interchangeable

A persistent anti pattern remains the belief that methods can be mixed and matched without consequence. A bit of Agile here, a platform team there, some API practices on top, and alignment will somehow emerge.

But methodologies encode assumptions. They make claims about ownership, feedback loops, and where learning happens. Ignoring those assumptions while adopting the vocabulary creates friction that no amount of tooling can resolve.

A better way to close the year

This is why Architectural Bytes should not end 2025 with predictions. The industry does not need more forecasts about what might happen next. It needs more discipline in how existing knowledge is applied.

The work ahead is not about discovering the next framework or trend. It is about creating a shared baseline and using well known methodologies deliberately, with a clear understanding of their consequences. AI will continue to accelerate everything, but acceleration without enablement only magnifies existing weaknesses.

What matters now is not seeing the future earlier than others, but being structurally ready when it arrives.

apidays Paris 2025 opened with a keynote that quietly reframed the entire event. Steve Lucas from Boomi did not speak about APIs in the familiar way. He spoke about the foundations that modern AI depends on. He talked about governance for sprawl, about lineage and sovereignty, about resilience and real time context. He described an ecosystem in which APIs are only the visible surface and where meaning, trust and coherence matter far more than any individual endpoint. His message landed with a calm certainty. Unless organisations strengthen what sits beneath their interfaces, the interfaces themselves will lose relevance.

Within the next keynote, Mark O’Neill continued this line of thought from the perspective of AI agents. He reminded the audience that agents are not patient consumers. They will not wait for clean, consistent interfaces. When APIs lack clarity or hide semantic gaps, agents simply route around them. They move through user interfaces or scrape other surfaces and they do so without asking permission. That behaviour breaks governance and blinds organisations to how their systems are actually being used. Mark argued that the industry needs to look beyond developer experience and accept that agent experience is becoming a first class design concern. To support this shift APIs need to express intent, purpose and constraints in a form that machines can interpret reliably.

The second conference day began with Andrew Humphreys who placed these themes into an architectural context. API Management is no longer one platform or one product category. It has become a loose constellation of gateways, async brokers, schema hubs, catalogs, security posture tooling and multi runtime control planes. These components coexist in a distributed landscape that resists centralisation. Andrew pointed out that this is not a temporary phase. It is the operating model of modern digital organisations. The real work ahead is not consolidation but federation, supported by governance and shared semantics.

Two practitioner talks gave these high level messages surprising shape. The first came from Santhosh Jose who works in the travel and cruise sector. His story was not about domain complexity or the challenge of modelling dynamic products. The real issue was far more basic. The standards exist but the tooling does not. His team works with OpenAPI every day, yet they had to build their entire automation layer themselves. They created a tool that converts OpenAPI files into Excel so that product owners and technical writers could update descriptions without touching YAML. They wrote another tool to enforce styleguides on legacy specifications. They even built a generator that provides new OpenAPI documents already shaped by those styleguides so solution architects do not start from scratch. And even after this considerable effort his roadmap slide read like a public call for help. He still wanted an editor for Overlays with a real preview mode, an interface for Arazzo so teams could design call sequences visually, server side code generation for the languages they actually use, deeper payload level observability for business KPIs and robust client SDK generation. None of this is available as polished, widely adopted tooling. His talk showed that everyday API work is far from industrialised even in organisations that follow the standards closely.

The second reinforcing story came from Dimitri van Hees who spoke about the Dutch government’s API program. At first glance one might expect the Netherlands to have access to the best government grade tooling available. Instead Dimitri explained that his team had to build almost everything themselves. They created an internal pipeline that validates OpenAPI documents, dereferences them, converts them between versions and formats, generates SDKs for tools like Bruno and Postman and enforces their API Design Rules automatically. Their ADR engine is not a commercial product. It is code they wrote because nothing else served their needs. Their Tools API that bundles specifications, verifies consistency and even transforms Arazzo definitions is also entirely home built. His story sounded almost identical to Santhosh’s. When standards advance faster than tooling, organisations do not stop using the standards. They build the missing tooling themselves and assume the burden of maintaining it forever.

Together these two talks created a clear pattern. The gap in the API landscape is not conceptual. It is practical. It is the gap between standards that have matured into precise definitions and tooling ecosystems that have not kept pace. Practitioners are not struggling with OpenAPI or AsyncAPI. They are struggling with the absence of a mature, widely available automation layer around them. The tooling deficit forces even advanced organisations to create their own infrastructure. This is one of the strongest signals that the API ecosystem is transitioning into a new era.

The AsyncAPI Ambassadors panel highlighted an important consequence of this shift. OpenAPI and AsyncAPI are often treated as documentation artefacts, but they are far more than that. They form the substrate for contract testing. Contract testing establishes trust between systems by verifying that what is promised on paper is what is delivered in practice. It is the first enforceable layer of reliability. It is the mechanism that turns interface descriptions into behavioural guarantees. Without it there is no stable foundation for automated integration and without a stable foundation there can be no agent ready capabilities. Trust becomes the currency that fuels the next generation of API ecosystems and contract testing is how that trust is earned.

Many in the API community have anticipated this direction. Kin Lane has long argued that APIs must carry shared meaning rather than isolated structures. Marjukka Niinioja’s involvement in APIOps Cycles to bring governance and consumer value into a continuous process. Jérôme Louvel explores how interfaces can capture operational stories. Jens Neuse highlights the importance of relationships and graph perspectives. Kristof van Tomme positions documentation as part of the system’s knowledge rather than a supplementary layer. These ideas converge on the same insight. Interfaces describe behaviour but without semantics they cannot communicate intent.

This insight is now shaping the tools that are beginning to emerge. Naftiko positions itself as a capability fabric, designed to provide organisational and agent context and to turn scattered APIs and SaaS services into predictable, policy driven infrastructure. Structr approaches the problem from the data and knowledge side and unifies rules, entities and user interfaces so that APIs naturally carry meaning. Dashjoin focuses on metadata and governance and treats the API simply as the expression of those deeper structures. PolyAPI takes a developer centred approach and does not attempt to model capabilities semantically. Instead it provides a more coherent way for engineers to orchestrate and compose services across distributed systems. This is a complementary movement. Some tools push upward toward semantics, governance and capability awareness while others push downward toward developer ergonomics and operational reliability. Both are necessary. One gives organisations the ability to express what they do. The other helps them execute those expressions consistently.

This context also clarifies the strategic pressure on established vendors. Integration platforms like Boomi will need to evolve beyond connectivity. They will need to incorporate semantic models, governance overlays, lineage insights and agent coordination. They will become capability control planes rather than simple orchestration engines. The shift from interface to capability is not a theoretical exercise. It is becoming a competitive necessity.

apidays Paris 2025 revealed that the future of APIs will not be defined by new formats or additional protocols. It will be defined by organisations’ ability to express meaning, trust and capability in a form that both humans and agents can understand. The work of 2026 will involve building semantic surfaces rather than syntactic ones, maturing standards into layered ecosystems rather than isolated artefacts, industrialising tooling so that organisations stop building everything themselves and embracing federated governance that spans multiple teams and runtimes. It will also involve expanding developer experience into agent experience and moving toward a capability specification that describes what systems are able to do in a structured and reliable way.

If organisations take these steps APIs will finally become what they were meant to be, the deliberate expression of what an organisation can do. If they do not, AI agents will continue to navigate around the gaps and the evolution of digital ecosystems will proceed without them.

The Ontologist

Are We Thinking About Ontologies Wrong?

This has been on my mind for a while now, the idea that one of the big things holding RDF back is the notion of global identifiers. RDF has been associated with the concept of URIs (eventually IRIs) almost from its inception, but there have been some fundamental issues when dealing with narrative structures (and especially conversation) that have me que…

Read more

10 months ago · 16 likes · 3 comments · Kurt Cagle

is one of those rare moments where two worlds, ontologies and APIs, start to sound like they are describing the same thing, just in different vocabularies.

His argument touches on something that those of us in the API space have been sensing for years. The world is messy. Meaning is contextual. Interfaces and data models do not exist in isolation; they live within evolving conversations. And maybe the biggest illusion we keep trying to preserve is that there could ever be something like a global model of truth.

Meaning emerges, not from models but from interaction

Kurt uses the example of a casual conversation at a cocktail party to show how people negotiate meaning through context. The term “bill” shifts its meaning depending on who is listening and what they already know. This small story captures something essential. Meaning is deferred until enough context exists to disambiguate it. Ontologists call this deferred classification.

In the world of APIs, this dynamic is mirrored every day. An API specification is not a final statement of truth. It is a conversation starter, a working agreement that evolves as producers and consumers interact. Within the APIOps Cycles, this continuous refinement is the heartbeat of the process. Design, deploy, observe, evolve. Meaning crystallises through use. It is less about defining everything up front and more about creating the right loops to refine understanding over time.

Scoped meaning and bounded contexts

Kurt questions the idea of global identifiers, arguing that all meaning is scoped to the authority that defines it. That idea aligns almost perfectly with how Capability Thinking views organisations. Each capability defines its own bounded context, its own local ontology. Within that boundary, the world makes sense and identifiers are stable. Across boundaries, translation and alignment are required.

In the API world, this is the reason federated API management has become so relevant. It recognises that APIs express localised worldviews. There is no single shared ontology across an enterprise. What we can build, however, are the structures to navigate between them. Capability Thinking provides those structures conceptually. Federated management provides them operationally.

Standards as social contracts

Kurt also draws attention to consensus and scope. When groups of people agree on how to use terms, they effectively create a scoped ontology, a contract for shared meaning. Standards emerge from this social process.

In API Thinking, standards and governance work in exactly this way. They are not there to impose control but to sustain coherence. Each team, each capability, has the autonomy to express its local view, yet governance ensures those views can be related and composed. This is what the APIOps Cycles describe when governance, design, and feedback are interwoven. Consensus becomes a dynamic and living process.

Context, intent, and affordance

Kurt’s example of “bill” shows that words are only meaningful within a context of intent and usage. APIs behave the same way. The field names in a payload tell us very little until we understand the capability behind them.

This is why Capability Thinking puts intent at the center. Instead of focusing purely on data or schema, it asks what action this API enables, what problem it helps to solve, and what capability it exposes to others. Meaning arises from affordance, not from syntax. It is a shift from describing the world to describing what we can do in the world.

Local identifiers and federated sense-making

Kurt’s reflection on local identifiers could almost be read as a description of federated API landscapes. Each domain issues its own identifiers under its own authority. Uniqueness exists only within context. The combination of value and issuing domain forms the qualified meaning.

In federated API management, we see the same principle. Instead of a single registry of global truth, we have interconnected catalogs that preserve local autonomy but remain discoverable through context. It is a living map of local ontologies that form the enterprise’s semantic fabric.

Evolving systems and continuous learning

What stands out most in Kurt’s writing is his view of knowledge graphs as evolving systems. They learn by refining themselves as new information arrives. They are not static models but adaptive representations of reality.

The APIOps Cycles embody the same idea operationally. APIs evolve through observation and feedback. Usage metrics, consumer experience, and telemetry all feed back into design. The API landscape becomes a learning system. It is, in a sense, a symbolic system that continually reshapes its own ontology based on interaction and evidence.

Capability Thinking adds another dimension to this. It ensures that this learning connects back to business purpose. Each iteration of an API is not just a technical adjustment but a refinement of how the organization expresses what it can do. Over time, the landscape becomes a living capability graph.

Shapes, schemas, and shared understanding

Kurt highlights SHACL as a powerful way to define shapes, structured patterns that describe how entities and relationships are expected to look. APIs have their own shape languages: OpenAPI, AsyncAPI, GraphQL Schema all define how interactions are structured and constrained.

These shapes enable validation and composition. More importantly, they allow shared understanding without demanding global uniformity. Within APIOps Cycles, these definitions are treated as living artefacts that evolve alongside the systems they describe. Patterns emerge, get recognised, refined, and sometimes retired. Governance in this context acts like the ontologist pruning the evolving taxonomy of interfaces.

From ontologies to capabilities

At the heart of both perspectives lies a belief that structure and meaning must evolve together. Kurt’s evolving ontologies and Capability Thinking’s evolving capabilities describe the same phenomenon. Each capability is a local ontology of intent and behaviour. Its API expresses that ontology to others.

When connected across an enterprise, these capabilities form a federated graph, not of data but of meaning and purpose. The relationships between them are governed through standards, feedback, and shared understanding. This is where the ontology and API spaces begin to converge. They are both about creating sustainable coherence in a world that refuses to be globally uniform.

Looking ahead

Kurt Cagle’s work reminds us that the boundary between symbolic knowledge systems and API ecosystems is thinner than it seems. Both are attempts to make meaning explicit without freezing it. Both rely on feedback and context to stay relevant. Both recognise that semantics live in interaction, not in definitions.

As API Thinking continues to evolve and as knowledge graph technologies mature, the two domains are likely to meet in the middle. We may soon speak of APIs as semantic surfaces over organisational ontologies or of knowledge graphs that learn through API telemetry. Either way, it will be the shared recognition that meaning is local, contextual, and evolving that brings these spaces together.

Human Interpretation as the Starting Point

The statement feels true the moment you hear it. Data alone never explains what is happening in a business process. A dataset shows that an order was created but reveals nothing about whether this reflects a final commitment or an informal intention. An event carries a familiar name yet speaks a dialect that only the producing team understands. Misaligned interpretation is often the real reason why integrations break and why APIs frustrate consumers. Teams assume they share a context while each of them carries a different one in their mind.

At the same time Mason’s statement risks being read too literally. If context lived only in people’s heads, large organisations could not function. Human understanding is essential, but it is fragile. People interpret things differently. People leave. People forget. Without shared structures, semantic drift becomes inevitable. This is why so much energy goes into externalising and stabilising context. Domain models, event semantics, capability maps, operating procedures and interface guidelines all exist because organisations cannot rely on personal interpretation alone.

Knowledge Graphs as Semantic Memory

This is also where Knowledge Graphs enter the picture. A Knowledge Graph is more than a clever data representation. It is a way of externalising relationships, meanings and assumptions that would otherwise remain buried in individual mental models. Knowledge Graphs create an explicit network of concepts, entities and links that represent how a business understands its world. They do not replace human context, but they capture and structure enough of it so that others can build on it without reinventing the meaning every time. In this way they become a form of semantic memory for the organisation. They make tacit context discoverable and explainable rather than allowing it to float invisibly between teams.

There is also the contrasting perspective that emerges when we recall Mason’s background. As the founder of MuleSoft he helped promote the belief that integration could be scaled through connectors, templates and catalogues of building blocks. The implicit message was that context problems could be solved through platform engineering. His remark now reveals the limits of that belief. Platforms accelerate connectivity. They do not create shared understanding. They solve the technical layer. They do not solve the semantic one.

It is equally important not to neglect the context that does appear inside data structures. Data never carries full meaning, but it does carry clues. The evolution of an event stream reflects workflow thinking. Field names reveal priorities. Relationships between entities show how teams understood their boundaries. Even the absence of certain attributes tells a story about what was considered irrelevant. These traces matter because they show the historical reasoning that shaped a domain.

Capabilities as Containers of Meaning

This brings us to Capability Thinking.

Capabilities describe what the organisation must be able to do, independent of systems or teams. Because they bundle purpose, responsibilities and concepts, they become containers of meaning where human context becomes stable. Once a capability is clearly defined, APIs become expressions of that capability rather than arbitrary technical pipelines. Integration becomes a conversation between capability boundaries instead of a negotiation between systems. Context becomes durable because it is anchored in organisational structure rather than individual memory.

Knowledge Graphs complement capability maps by providing the semantic fabric that connects concepts, events, responsibilities and data. They reveal how meaning flows through the organisation. They expose contradictory definitions. They show where teams quietly diverge in their understanding. Together, capabilities and Knowledge Graphs offer a path to externalise context without freezing it into rigid structures. They create shared organisational memory that improves over time.

There is also an important implication for AI. Generative models can support summarisation, highlight semantic gaps and work with Knowledge Graphs to provide reasoning paths. But they cannot originate the tacit meaning that defines a capability. They operate on the visible traces of context, not on the invisible human reasoning behind them.

Toward Shared Organisational Context

The closing reflection brings the elements together. Mason is right that context does not arise from data alone. It begins in human interpretation. But if it stayed there, organisations would be unable to scale their digital efforts. The real challenge is to move context from individual minds into shared structures. Capability maps, semantic models, Knowledge Graphs and disciplined API practice make this possible. They turn fragile personal understanding into coherent organisational memory. Context may originate in the mind, but it becomes powerful only when it is shared.

For years, we have been talking about gateways. We discussed whether we need one per platform, per service, or per domain. We debated where they should live and what they should enforce. We turned them into symbols of security and governance, and sometimes into scapegoats for everything that felt ungoverned.

Looking back, it feels like we have been debating the wrong thing all along. The gateway was never the real question. It was just the most visible symptom of a deeper architectural anxiety: the need to make distributed systems feel contained.

The End of a Debate That Never Really Existed

The gateway debate became a stage on which we rehearsed questions of ownership, responsibility, and trust. Who controls the boundary between teams? Who defines what is safe to expose? Who decides what should be reused?

None of these questions can be answered by configuration or by routing. They are questions of intent, alignment, and organizational design. The longer we stayed in the gateway discussion, the less we talked about these foundations.

Now the world around us has moved on. We live in an era of federated systems, composable architectures, and agent-driven interactions. The edge has become porous. It shifts constantly, and the idea of a single point of control feels outdated. The gateway, once a reassuring symbol, starts to look more like a relic of centralisation.

The Edge Was Always a Fiction

The concept of an edge once made sense. It separated the internal from the external, the trusted from the untrusted, the known from the unknown. But real systems were never that clean. APIs blurred these lines. Data moved between organisations. Services called each other across boundaries that no longer meant what we thought they did.

Today, that fiction has fully collapsed. Boundaries are contextual, not spatial. They depend on teams, policies, and intent. They exist where collaboration needs coordination, not where firewalls once stood. The gateway was a map of comfort, not a reflection of reality.

From “Gateway Thinking” to Capability Thinking

When we stop seeing architecture as a network of controlled edges and start seeing it as a landscape of capabilities, the conversation changes. We no longer ask where to place the gateway. We ask how to express intent, how to define ownership, and how to align value creation with exposure.

Capabilities describe what an organisation can do, not how traffic flows. They make architecture about purpose again. In this view, APIs are expressions of capability. They are touch-points, not borders. The question is no longer “how do we secure the gate” but “how do we make the capability usable, measurable, and meaningful.”

This shift moves us from managing interfaces to managing potential. It makes the gateway debate irrelevant, because once you start designing for capabilities, the gateway becomes an infrastructural consequence, not a conceptual centrepiece.

Governance Without Borders

The next generation of governance does not rely on checkpoints at the edge but on shared understanding within the ecosystem. It emerges from clear ownership, consistent standards, and distributed accountability.

Teams that work in a federated model no longer need a single gateway to enforce rules. They need common principles and shared feedback loops. Governance becomes invisible when it works, and that is the direction architecture is heading. The more intelligent our infrastructure becomes, the less we need visible control surfaces.

The New Boundary: Intent

If there is a new edge, it is the boundary of intent. Every API, every event, every model call carries a purpose. The clarity of that purpose defines the quality of interaction.

This is where the architectural conversation meets the emerging world of AI Gateways, Model Context Protocols, and agent-driven platforms. These systems do not replace gateways; they reveal how intent itself becomes the new interface. We no longer guard access but curate meaning.

In

I explored how mediation shifts from routing to reasoning, and how this shift challenges the way we think about ownership and interaction. The same principle applies here. The edge dissolves, but intent remains. It is what connects human design with machine interpretation.

Leaving the Gate Behind

The gateway served its purpose. It gave shape to an age that needed structure. It taught us about exposure, protection, and consistency. But architecture evolves by outgrowing its metaphors.

Today, the most interesting work happens where boundaries blur. In federated API management, in composable ecosystems, in agent collaboration, and in capability alignment. The edge is no longer the point of control. It is the point of connection.

So perhaps it is time to stop defending the gate and start designing the garden.

Further Reading

This piece closes a reflection that began with

, continued through

, and unfolded in

. Together, they trace how architecture moved from control to connection, and how we can now move beyond both toward intent and capability.

Yet the more I think about it, the more I suspect that the conclusion points in the wrong direction. Perhaps it is not event streaming that has reached its limits. Perhaps our organisations have simply reached the limits of what they can achieve with it under the current way of thinking. The technology has not failed. Our ability to turn it into something meaningful has.

We see this pattern often. A promising technology enters the scene and we rush to adopt it. Once the infrastructure is operational, we assume we have acquired the capability it represents. Kafka clusters are deployed, pipelines built, dashboards integrated and the work is declared complete. Yet the way we make decisions, the speed at which we respond and the structure of responsibilities change very little. What we have gained is a tool, not a capability.

From Tools to Capabilities

Capability Thinking helps to illuminate this gap. A capability is not a piece of software but the ability to achieve a particular outcome. It depends on purpose, structure and shared understanding long before it depends on technology. Many organisations reverse this logic. They begin with the tool and trust that clarity and purpose will follow. Kafka becomes a symbol for real-time awareness even when no one has defined what should happen because of that awareness. Pipelines appear without explicit ties to the decisions they are meant to support. The result is an impressive landscape of infrastructure that is oddly disconnected from business intent.

Integration Thinking deepens the analysis. Integration is not simply the act of connecting systems. It is the way capabilities interact with one another. APIs, events and streams are just different ways of articulating that interaction. A synchronous API is a direct coordination. A stream is a signal that something has occurred and that other capabilities may want to respond. When a stream is treated purely as a high-speed data conduit, it loses its meaning. It is then no surprise that the initial enthusiasm fades, because the interaction was never truly defined.

The Maturity Gap

Many so-called event-driven efforts today are not driven by meaningful events at all. They are driven by replication and distribution. They consist of large collections of topics and pipelines with unclear ownership and semantics. Observability often means hunting through logs rather than understanding behaviour. Instead of fostering a responsive enterprise, we create distributed complexity that simply moves faster than before. The technology is not the problem. The maturity around it is.

From a capability perspective, event streaming only matters when it changes how a business senses and reacts. It should enhance situational awareness and shorten the path from observation to action. Achieving this requires clear boundaries between domains, a shared vocabulary and alignment on outcomes. These steps are frequently skipped because they seem too abstract or slow compared to the thrill of deploying infrastructure. Yet without them, streams become little more than noise. As excitement fades, it becomes easy to misread our own lack of capability as evidence that the technology itself is declining.

The Next Curve

Integration Thinking points to a more nuanced future. We are moving toward an environment that resembles a mesh of interacting capabilities rather than a central event bus. Each capability communicates in the mode that best fits its responsibility: synchronous when coordination is needed, asynchronous when awareness is enough, semantic when shared meaning matters and intelligent when adaptation is required. In this world, event streaming does not fade away. It becomes part of the infrastructure, almost invisible, similar to how HTTP eventually vanished into the background. The real measure of maturity is not how many clusters are running but how easily capabilities can sense and respond to change.

The conversation should evolve. The relevant question is not whether event streaming is dying. It is whether we are ready to build on what event streaming made possible. The real value sits above the technical layer. It lies in designing adaptive capabilities, combining event signals with APIs and applying governance that brings coherence to the landscape. The next challenge is not throughput but understanding. It is about designing interactions based on intent and outcomes rather than erecting pipelines simply because we can.

Event streaming has not topped out. Our imagination has. What has reached its limit is the set of patterns we have been working with, not the potential of the technology itself. Once we begin to map the capabilities behind the events, the story shifts. Maturity does not mark decline. It marks the transition from technology novelty to foundational infrastructure. The question is whether our organisations are ready to think beyond the tool and embrace what it was always meant to enable.

Starting from Tools Instead of Governance

The public site for the DeutschlandStack is neatly structured. It shows layers, technologies, and architectural visions. It highlights modularity, reuse, and open standards. The heise coverage frames the D-Stack as the backbone of the digital state, meant to ensure the basic digital functions of public service delivery. It mentions building blocks such as identity, payment, and signature services that should enable interoperability across agencies. In principle, that is exactly what a modern state needs. The newer article goes further, presenting a “landkarte” of the platform with six interlocking layers — from infrastructure to user-access — and a maturity model for included technologies. Consultation is open until the end of November. Yet the map shows only the technological terrain. There is no comparable landscape for governance, accountability, or decision-making. The blueprint for the tools exists; the blueprint for the rules does not. That is where the imbalance begins. Governance, in a project of this scale, is not a secondary topic. It is the first capability that must exist before any technology can be meaningful. A stack without governance is simply a collection of tools that happen to live in the same diagram. Both heise pieces already hint at the need for governance. They mention calls for a dedicated task force and a federated operating model coordinated through FITKO and the IT Planning Council. The recognition is there, but the structure is still missing.

A Capability Lens on the DeutschlandStack

Looking at the DeutschlandStack through the lens of Capability Thinking changes the perspective. A capability defines what an organisation must be able to do to deliver value. It is not about the specific tool used to do so. For government, these capabilities include verifying identity, enabling secure payments, sharing data across ministries, or ensuring compliance with data-protection law. These are the true building blocks of a digital public sector. Everything else, from APIs to infrastructure, exists to support them. The current documentation lists technology layers but not the capability map that ties them to policy outcomes. There is no visible structure showing who owns which capabilities, how they interact, or how success will be measured. That omission matters. Without it, the stack remains a technical artefact detached from its purpose.

Governance as the First Capability

Governance should not be treated as an afterthought. It is a capability in itself. The ability to coordinate, decide, and evolve collectively. In a federal system like Germany’s, governance is the hardest part. Each level, from federal to municipal, owns its own systems, budgets, and priorities. Aligning them requires more than a shared toolset. It requires a shared capability for decision-making and trust. If the DeutschlandStack begins with tools and leaves governance to evolve later, it risks repeating the same fragmentation it was created to overcome. Each level may adopt parts of the stack differently, creating new silos under the label of standardisation. The latest heise article notes that the stack will encompass strategic and organisational framework conditions alongside technology. Yet describing a framework is not the same as embedding one. The consultation still focuses mainly on technical standards and tool inclusion, which shows governance remains reactive rather than foundational.

API Thinking: Interactions Over Infrastructure

If Capability Thinking defines what government must be able to do, API Thinking defines how those capabilities connect. APIs are not just integration points. They are contracts between capabilities. They define how a digital identity service interacts with a licensing authority, how payment services link to public registers, or how compliance checks are automated. The DeutschlandStack promises interoperability, but the current narrative still reads like an infrastructure story rather than an interaction story. The question is not whether it runs on containers but whether it can express and evolve consistent APIs across organisations. That requires an API Strategy: a governance system for how APIs are designed, published, versioned, and reused across federal and state boundaries. There is no visible sign of that yet. Without it, reuse remains theoretical.

From Tools to Operations: The APIOps View

To understand what is missing, it helps to apply the APIOps Cycles method. It defines a continuous process for designing, delivering, and governing APIs as products. It begins with strategy, moves through design, delivery, publishing, audit, and improvement. It is not a checklist but a feedback loop. When this logic is applied to the DeutschlandStack, the gap becomes clear. The initiative has started in the middle of the cycle with delivery and architecture but skipped the earlier stages that define purpose and governance. There is no shared API Product Strategy for the public sector. No consistent consumer experience for agencies and states. No federated audit or improvement cycle. This is not a technical issue. It is a structural one. A stack that starts in the middle of the cycle cannot close the loop.

The Stack as a Capability System

The DeutschlandStack should be understood not as a set of components but as a capability system that connects technology, people, and governance. Each capability in particular identity, payments, messaging, consent, or data exchange should be clearly owned, described, and exposed through APIs. Each should have measurable maturity, adoption metrics, and defined ownership across levels of government. Once those are in place, the technical layers of the stack begin to make sense. Infrastructure becomes one enabling layer. The real value lies in defining and connecting the capabilities themselves. Governance then becomes the invisible API between ministries and states. It defines who may call what, under which conditions, and how the system evolves without breaking.

Federated Governance as an Operating Model

A national digital stack cannot be governed by a single committee. Governance has to be federated, distributed across roles and responsibilities that reflect how government actually operates. Team Topologies provides a useful metaphor. Platform teams maintain the core of the stack. Stream-aligned teams in ministries and municipalities build services on top. Enabling teams promote design standards and security practices. Complicated subsystem teams own specialised capabilities such as identity or payments. This is how federated systems stay coherent without becoming centralised. If the DeutschlandStack adopts this kind of role clarity early, it can avoid becoming just another central platform that others resist.

Ecosystem and Value Creation

Seen through Capability Thinking and API Thinking, the ecosystem around the DeutschlandStack looks different. It shifts the focus from vendors and tools to capability contributors.

• Vendors contribute implementations of shared capabilities.

• States and municipalities act as capability owners.

• Citizens become capability beneficiaries.

• Governance bodies act as capability enablers.

This reframing changes incentives. It also supports open participation. If capabilities and APIs are described transparently, smaller vendors and open-source communities can take part on equal terms. That is what digital sovereignty should look like. It is not about exclusion but about structured participation.

Governance as Code

To make this kind of system work, governance itself has to become operational. Policies cannot live only in PDFs. They need to be expressed as APIs, rules, and automated checks that systems can enforce. The APIOps Cycle supports this idea. Strategy and design translate policy into artefacts. Delivery and publishing bring them to life. Audit and improvement close the loop with evidence and feedback. Governance then becomes executable. It turns into a living capability that adapts over time.

What Happens If We Don’t Fix It

Without Capability Thinking, the DeutschlandStack risks turning into a list of technologies detached from the outcomes it was meant to deliver. Without API Thinking, it lacks the connective tissue that allows those capabilities to interact and evolve. Without APIOps, it has no mechanism for continuous learning and improvement. The result would be familiar: duplication, slow adoption, and loss of trust.

From Tool Catalogue to Capability Platform

If Germany truly wants to build a sovereign and reusable stack, the first layer should not be infrastructure but governance and capabilities. Start by mapping what the public sector must be able to do. Define those as capabilities. Expose them as APIs. Govern them through continuous APIOps Cycles. Then add the tools that make them work.Only in that order does the stack become more than a diagram.

Closing Reflection

The DeutschlandStack could indeed become an essential foundation for genuine interoperability and sovereignty in public services. But technology alone will not carry that promise. Real sovereignty begins with the ability to govern, evolve, and collaborate across federated levels of administration. It means starting with governance before code, with capabilities before tools, and with APIs before infrastructure. The uncomfortable truth is that digital sovereignty is not first a technical achievement but an organisational one. Until governments treat governance itself as a digital capability, every stack will remain a catalogue of tools, impressive on paper but hollow in practice.

That was the central message behind my talk at the Nordic APIs Platform Summit in Stockholm last week and, in many ways, a reality check for everyone experimenting with TypeSpec.

TypeSpec looks convincing on paper. It promises a clean, type-safe language for defining APIs, and it solves some long-standing pain points that OpenAPI cannot: verbosity, inconsistent design, and the endless maintenance of description files. The syntax is elegant, the generator story is strong, and the potential is real.

But tools do not exist in a vacuum. They exist inside organizations with history, habits, and platforms that rarely start from scratch. And that is where the real story begins.

The first friction point: the illusion of replacement

When people first encounter TypeSpec, they often see it as a replacement for OpenAPI. That expectation quickly leads to disappointment.

OpenAPI is not going away. Too many tools, portals, SDK pipelines, and governance systems rely on it. The moment a team tries to go all in on TypeSpec, they meet friction from every direction: incompatible toolchains, broken integrations, and skeptical platform teams.

The successful ones do not replace; they redirect. TypeSpec becomes the upstream source of truth, while OpenAPI remains the generated artifact that everything else still consumes.

That hybrid reality is the only sustainable path forward for now.

The second friction point: the scaling paradox

The first TypeSpec project almost always works beautifully. One team, one service, one definition. They move faster, make fewer mistakes, and wonder why everyone else has not switched yet.

Then the second team joins. Suddenly the elegant experiment becomes a governance problem. Pagination looks different, error responses diverge, naming conventions drift.

The hard truth is that TypeSpec does not prevent inconsistency; it just exposes it earlier.

The real work begins when teams build shared libraries: decorators, templates, and reusable models that encode organizational standards. That is where governance as code stops being a phrase and starts being a compiler rule.

The third friction point: governance culture

Every organization I have worked with claims to have API governance. In reality, it is usually a set of well-written documents, outdated templates, or guidelines nobody reads. Governance lives in Confluence, not in CI/CD.

TypeSpec flips that model. The rules that used to be reviewed manually become enforceable at compile time. Consistency stops being a negotiation and becomes a property of the system.

But that shift is not only technical. It is cultural. It changes how architects and developers interact. It challenges the idea of review boards as gatekeepers and requires organizations to treat governance as a service, not a ceremony.

The fourth friction point: platform alignment

Even when teams embrace TypeSpec, platforms often lag behind. CI/CD systems need new validation steps, portals need new importers, and governance tools need to adapt.

This friction is not failure; it is integration cost. The organizations that succeed treat TypeSpec adoption as part of their platform evolution, not as an isolated developer initiative. The platform must grow with the language.

The quiet shift underneath

Once governance becomes executable, something interesting happens. The conversation moves beyond REST.

TypeSpec can already output OpenAPI, but it is steadily expanding toward AsyncAPI, GraphQL, and even data product contracts like ODPS.

Suddenly we are not just defining APIs; we are defining interfaces in the broadest sense.

That is the real promise: a unified contract language that underpins the entire interface ecosystem with shared semantics and governance built in.

What we learn when the experiment ends

TypeSpec is not a revolution; it is an evolution.

It will not fix broken communication between teams or weak ownership structures. But it gives organizations a concrete way to codify good practice and make it verifiable.

The teams that benefit most are those that already think in systems, governance, and feedback loops.

For them, TypeSpec is not another framework; it is a bridge between architecture and delivery.

After the session in Stockholm, several people told me they came expecting a tooling talk but left thinking about governance. That is the right takeaway.

The real challenge is not writing TypeSpec; it is creating an environment where consistency, not control, becomes the natural outcome of the way we build.

Closing Reflection

Every new framework arrives with promises of order. But in the end, real progress does not come from syntax; it comes from the discipline we build around it.

TypeSpec is just the latest expression of a much broader shift where design, governance, and delivery finally converge.

In API Thinking, we treat interfaces not as isolated endpoints but as expressions of shared intent. TypeSpec gives that intent a precise and enforceable form. It is the missing connective tissue between strategy and code, a way to let standards evolve with teams instead of being enforced against them.

This is where platform governance becomes truly federated. Not a single team telling others how to build, but a system that embeds good decisions into the development flow itself.

When a rule compiles instead of being discussed, governance stops being a bottleneck and becomes an accelerator.

Maybe that is the real lesson from Stockholm. The frameworks will keep changing, but the organizations that succeed are the ones that turn architecture into something executable, where consistency is not mandated but emerges naturally from the way teams work.

Author’s Note

I am writing these thoughts while on vacation in the Middle Rhine Valley, surrounded by vineyards, steep hills, and the quiet rhythm of the river. It is a place that has learned to evolve over centuries without losing its identity, something our digital ecosystems could learn from.

After half a week of intense conversations at the Nordic APIs Platform Summit, the calm of this UNESCO World Heritage landscape makes it easier to see patterns that are hard to spot in the daily rush.

The distance helps. Governance, architecture, and consistency are not about control; they are about finding balance over time.

Maybe that is what we should all be aiming for. Systems that last because they are allowed to adapt, not because they are forced to comply.

The more I talk with people in projects, the more I notice how gateways have quietly taken over our mental models of architecture. I hear phrases like “gateways that talk to each other” or “every service needs its own gateway.” They sound reasonable, but they reveal how far we have drifted from the original intent.

This reflection continues the conversation started in

and

Both questioned how gateways became symbols of control instead of instruments of connection. This time, the focus shifts to what happens when the metaphor goes too far, when we begin to imagine gateways as if they were participants rather than infrastructure. Somewhere along the way, the means became the message, and the tools began to talk louder than the systems they were meant to serve.

The Echo Chamber of Gateway Discourse

In “When Gateways Start Solving the Wrong” I explored how gateways were assigned responsibilities that do not belong to them. They became instruments for solving governance, lifecycle, and policy problems instead of focusing on exposure, access, and protection. In “If Not the Gateway, Then Where” I asked where value actually lives once we move beyond the tool. I argued that boundaries should emerge from the value we create, not from the tools we happen to have.

Yet the conversations in the field still circle around the same misunderstandings. People talk about gateways talking to gateways as if this were an elegant pattern. Others claim that every service should have its own gateway to ensure autonomy and compliance. These statements are not only misguided, they show how deeply we conflate infrastructure with architecture.

How We Got Here

This confusion has roots. The last decade of API management was shaped by marketing and by the rise of platform engineering. The gateway became the visible anchor for everything that felt abstract about APIs: security, visibility, consistency, control. The more we talked about “API-led” and “governed-by-default,” the more we replaced reasoning about purpose with reasoning about placement.

Once micro-services entered the picture, the multiplication began. If one gateway helps, then a gateway for every service must be better. It sounded like empowerment, but in practice it created an ecosystem of intermediation, not of interaction. Each gateway became a checkpoint, not a connector.

Gateways Are Not Conversations

The idea that gateways should communicate with each other shows how distorted our view has become. Gateways do not talk. They route, protect, and observe. Treating them as participants in conversations between systems is like mistaking a microphone for a musician. It makes the infrastructure visible where the focus should be on the interaction itself.

When two gateways begin to exchange requests, what we actually build is a hidden integration layer that no one wants to take ownership of. The architecture looks more structured on paper, but in reality it becomes more fragile. Complexity grows in the very place that was supposed to simplify.

When Every Service Gets a Gateway

The “gateway per service” idea is another variation of this thinking. It sounds aligned with autonomy and scaling, but it multiplies complexity instead of reducing it. Each gateway introduces its own configuration, monitoring, and risk of divergence. Autonomy without coherence turns into fragmentation.

Look at your landscape diagram. If gateways outnumber APIs, you are no longer building an ecosystem. You are building a control mesh. In terms of the Data Interface Quadrants, this pattern often bleeds across boundaries. What belongs to internal collaboration ends up exposed as if it were external. Gateways should not live inside those quadrants at all. They belong to the edge, not to the fabric of internal interaction.

The Real Role of the Gateway

A gateway still has a role, but it is limited and specific. It manages authentication, authorisation, routing, and observability. It enforces rules. It is not there to represent value or ownership. In If Not the Gateway, Then Where I argued that capabilities, not tools, define where value sits. The same applies here. The gateway supports the flow of value but does not define it.

When we start seeing gateways as enablers instead of central actors, architecture begins to regain its shape. The edges become thinner and the core more meaningful. We no longer confuse control with clarity.

From Gateways To Capability Surfaces

If we stop drawing gateways first and instead start with value chains, the picture changes. Boundaries become defined by capabilities, not by network devices. APIs become visible as expressions of intent, not as routes through hardware.

In that world, gateways are background mechanisms. They enforce, they protect, but they no longer shape how we think. This is where API Thinking helps: it moves the attention back to who consumes, why they consume, and what value the interaction brings. Those are the real architectural questions.

Lost in Translation

The word “gateway” became a metaphor for safety in a complex world. It promises protection against chaos. But that promise hides a cost. It keeps us from confronting harder questions about design, ownership, and interaction.

We set out to build architectures for collaboration and exchange. We ended up building architectures of control. The shift happened slowly, disguised as best practice. But if your diagrams show more gateways than APIs, it is time to admit that something went wrong. You do not have an API strategy. You have a control problem.

A Short Addendum: The Rise of AI Gateways

The pattern does not stop at APIs. It is now reappearing in the world of AI under new names: AI Gateways, Agent Platforms, and the Model Context Protocol. Each of them promises to simplify the interaction between systems and models, to make context flow seamlessly, and to coordinate communication between agents.

But if we look closer, the language sounds familiar. These “AI Gateways” start to negotiate, to orchestrate, even to talk to each other. It is the same architectural instinct that once made API gateways appear as actors in their own right. The story repeats, only with more intelligence and less visibility.

In

I explored how this new generation of gateways extends the same logic we have already struggled with in API architectures. They mediate, abstract, and promise control, yet they can easily become new blind spots. Once again, we risk confusing the layer that connects with the one that defines value.

The myth of the talking gateway is no longer confined to HTTP. It is alive in AI-driven interaction, where tools gain agency faster than we can reason about their purpose. The challenge remains the same: how to design systems where intent, not mediation, defines architecture.

A Final Thought

Read this piece as the quiet conclusion to the reflections that began with When Gateways Start Solving the Wrong and If Not the Gateway, Then Where. The first post questioned why gateways started solving problems they were never meant to own. The second asked where value lives once we look beyond the tool. This one brings both ideas together and asks why we keep returning to the same conversation.

The myth of the talking gateway is not about technology. It is about projection. It shows how easily we turn tools into actors and how architecture starts to serve the comfort of control instead of the flow of value.

So here is the question that remains: what would your architecture look like if the gateways finally stopped talking?

“Any particular tools you’d recommend alongside the gateway to handle this business logic?”

It is the right question because it moves the conversation from what not to do in the gateway to how to decide where logic should live instead.

From tools to intent

This is where API Thinking becomes essential. It starts with intent rather than technology. Every interface exists to expose a capability, connect data, or deliver an experience. Once we understand that intent, tool choices and placement follow naturally. API Thinking begins with a few simple questions:

• Who consumes this interface?

• What value does it create?

• Which boundary does it cross—business, data, or policy?

Without those answers, teams make placement decisions out of convenience instead of design.

The Data Interface Quadrants as a map

The Data Interface Quadrants (DIQs) give structure to that intent. They describe where an interface sits between data ownership and data purpose:

1. Raw Data (Internal) – close to the source, minimal logic

2. Aggregated or Transformed Data (Internal) – enriched inside the domain

3. External and Reusable Data – standardised and governed for reuse

4. Product-Specific Interfaces – designed for a concrete consumer or use case

Each quadrant comes with different responsibilities. Logic that defines meaning or context belongs near the data (Quadrants 1–2). Logic that defines policy or exposure belongs in governance layers (Quadrant 3). Logic that defines experience belongs in the product space (Quadrant 4). The gateway plays its natural role in Quadrant 3, where governance and exposure matter, but the logic in the other quadrants should stay within the domains and products that own it.

Capabilities as the Missing Link

Kin Lane’s recent piece What Is a Capability adds another dimension to this discussion. He describes capabilities as business aligned functions that connect purpose with implementation. A capability, in his view, is not just an API or endpoint. It is a unit of business meaning that is clearly named, bounded, discoverable, and governed.

This framing helps clarify what belongs where. If a piece of logic can be described as a reusable, composable, and discoverable function that carries business semantics and metadata, then it deserves to exist as a capability, not as code hidden inside a gateway plugin. Capabilities live within domains, not on the edge. The gateway’s job is to enforce access to them, not to become one of them.

Kin’s thinking also reinforces the connection between API Thinking and capability literacy. API Thinking ensures that we start from intent and interaction. Capability literacy ensures that we can model and govern what that intent becomes once it materialises as interfaces.

Making placement decisions

A few examples illustrate how this helps in practice:

Composition and orchestration

When combining or aggregating data for a specific experience, you are in Quadrant 4. Use a Backend-for-Frontend or a dedicated composition service rather than embedding that logic at the edge.

Policy and consent

Cross-cutting enforcement belongs in Quadrant 3. Gateways and policy engines such as OPA or Styra fit this purpose.

Domain rules and enrichment

If the goal is to apply pricing, eligibility, or scoring logic, that sits in Quadrant 2. Domain services or workflow tools should own it close to the data.

This perspective turns placement into a capability question.
Who owns the rule, who changes it, and how reusable is it across domains?

Pragmatism with awareness

Shortcuts will always exist, and that is fine. What matters is awareness. If you know which boundary you are crossing and have a plan to move logic later, you are making a deliberate trade-off, not an accidental one. Architecture does not need purity; it needs consciousness.

From Pattern Literacy to Capability Literacy

Understanding architectural patterns is important, but it is only the first layer.
Pattern literacy helps us reason about structure. Capability literacy helps us reason about value.

Capability literacy means being able to describe what a system does in terms of business intent. It is the ability to name, govern, and evolve those functions as reusable and observable capabilities. It connects business architecture and API design and helps organisations see APIs not as isolated endpoints but as expressions of capability.

When teams develop both kinds of literacy, the question of where logic belongs stops being technical. It becomes an act of intent, ownership, and design.

Closing thought

The next frontier of API architecture is not another feature inside the gateway. It is the ability to think and talk about capabilities clearly.

When we align API Thinking, Data Interface Quadrants, and capability literacy, we gain a common language for deciding what belongs where and for keeping gateways as what they were always meant to be: places of governance and trust, not containers for business logic.

But the truth is that this feature exists not because the API Gateway pattern required it but because customers insisted on it. And customers insisted not because they had a deep understanding of gateways but because they were looking for shortcuts. They wanted a way to push business logic out of their services and into the infrastructure.

Kong is not alone in this. Almost every vendor in the API management space has responded to similar demands. Features are often added because “the market asked for it,” even when they blur the line between platform and product. Over time this erodes the very boundaries that patterns like the API Gateway were supposed to establish.

The role of a gateway is clear. It handles cross-cutting concerns such as security, quotas, token introspection, tenant context, and consent checks. These rules are broad, relatively stable, and belong at the edge. The moment gateways are asked to check inventory, calculate discounts, or route premium customers differently, they stop being gateways and start becoming containers for hidden business logic.

We have seen what happens when infrastructure absorbs responsibilities it should not carry. In the past, integration middleware and ESBs became overloaded with business rules. The result was brittleness, opacity, and a loss of agility. Vendors did not set out to create that complexity, but they delivered it because customers asked loudly enough.

The uncomfortable truth is that Request Callout is not a breakthrough. It is a compromise. Vendors like Kong build what customers demand, even when those demands run against the purpose of the gateway pattern. And the customers who celebrate these features often pay the price later in higher latency, complex debugging, and unclear ownership of logic.

A gateway is not a product. It is not a workflow engine. It is not the place to hide business rules. Vendors will continue to deliver what the market asks for, but it is up to us to stop asking for the wrong things.