Over the past weeks, I kept coming back to the same question from different directions. Can a modern HTTP API already be legacy? Is an HTTP interface really the right boundary for an API product? Does a Bounded Context define the API around it? Is Design First the same as writing the OpenAPI document first? And what happens to developer portals when the consumer is no longer necessarily a developer? These questions became six separate LinkedIn articles.

At first, they looked like different API topics. Looking at them together, however, a common pattern becomes visible. We expect the API to carry too many boundaries at once.

An HTTP interface describes how systems interact. A domain model gives meaning to concepts within a particular context. A product creates value for a consumer. An API description formalizes parts of an interface. Deployment adds runtime information. A portal provides an interaction surface. All these things are connected. They are not the same thing. And the problems start when we behave as if they were.

When a modern API becomes legacy

This became particularly visible while thinking about legacy. We usually associate legacy with technology: old platforms, old protocols, old programming languages. But an API does not need to be technically old to become difficult to change. It can run on a current platform, expose HTTP and have a perfectly valid OpenAPI description while the organization gradually loses the knowledge surrounding it. Why does this API exist? Who consumes it? Which business capability does it support? Which decisions shaped its contract? What depends on behaviour that nobody wants to touch anymore? The interface alone cannot tell us.

Seen this way, legacy is not only about ageing technology. It can also emerge when the distance between a system and our understanding of it continues to grow. That thought leads directly to another boundary problem.

An HTTP API is not automatically an API product

Once we start talking about APIs as products, it is tempting to put the product boundary around the technical API. But products are not defined by controllers, endpoints or deployment units. They are defined around consumers, problems and value. One API product may require several technical APIs. The same technical API may participate in different products or journeys.

HTTP remains an important interface boundary. It simply answers a different question. It tells us how interaction takes place. It does not tell us where the product begins and ends. The same caution applies when domain modelling enters the discussion.

A Bounded Context is not an API template

Domain-Driven Design gives us powerful tools for establishing modelling boundaries. A Bounded Context tells us where a model, terminology and set of rules remain meaningful and consistent. That can be extremely useful for API design and ownership. But it does not follow that every Bounded Context should expose exactly one API or that its internal model should become the external contract. Consumers cross that boundary with their own context. Their tasks, terminology and expectations may differ from those of the provider. Domain boundaries can therefore inform API boundaries without determining them. This distinction becomes important before the first line of OpenAPI is written.

Design First starts before the specification

Specification First is useful. Creating an OpenAPI description before implementation enables review, mocking, contract testing, parallel development and automation. But it is possible to write the specification first and still design the wrong API. The questions that matter initially are different.

Who is the consumer? What are they trying to achieve? Which capability should be exposed? Which interactions belong together? How does the API relate to products and interfaces already present in the landscape?

Only then does formalization become useful. A more meaningful sequence is therefore:

Design → Contract → Code

The specification represents decisions made during design. It should not be mistaken for the design process itself. And even that contract does not necessarily contain everything we eventually need to know about the API.

Context appears over time

An API description is created at one point in the lifecycle, but the API accumulates context afterwards. Deployment environments become known. Runtime endpoints appear. Consumers start depending on behaviour. Ownership may change. Operational information becomes available. Not all of this belongs in the original description. OpenAPI Overlays are interesting in this context because they provide a mechanism for applying additional information without having to turn the original OpenAPI description into the container for every lifecycle concern. The important idea is broader than Overlays. Information should enter the landscape when it becomes authoritative. Trying to make one artifact represent design, deployment, governance, operations and product context eventually makes that artifact less precise rather than more complete. Agents make this problem even more visible.

A portal is only one view of an API landscape

Developer portals were largely designed around a human journey. A developer searches for an API, reads its documentation, requests access, receives credentials and starts integrating. An agent introduces another interaction model. It may need to identify a capability, understand how that capability can be invoked, determine whether it has the authority to perform an action and then execute it.

That could involve MCP, tool definitions, registries or other mechanisms. There is no single agent discovery model emerging yet. But one thing already becomes clear: asking an agent to navigate the same information architecture we created for human developers is unlikely to be sufficient. The information underneath the portal becomes more important than the portal itself. Capabilities, contracts, constraints, ownership, authorization and relationships need to become machine-readable and connected. And this is where the six individual observations start to converge.

From APIs to API landscapes

In our earlier TechRadar post, Understanding API Landscapes, Not Just Managing Them, we argued that an API inventory is not yet an API landscape. Knowing that an API exists is useful. Understanding how it relates to products, consumers, capabilities, teams, systems and runtime dependencies is something different. The questions explored in the six LinkedIn articles explain why this distinction matters. If the technical API is not necessarily the product boundary, if a Bounded Context does not automatically define the external contract, if design begins before the specification, if deployment context emerges later and if different consumers need different ways of discovering capabilities, then no single API artifact can represent the complete picture. Nor should it.

OpenAPI should remain good at describing interfaces. API management should remain good at managing runtime exposure and policies. Developer portals should remain good at supporting human consumers. Enterprise Architecture should remain good at modelling capabilities, applications and organizational context. The missing piece is not another master artifact that replaces them all. It is the knowledge connecting them.

Which API supports which capability? Which product exposes it? Which consumers depend on it? Which domain context gives its concepts meaning? Which team owns it? Which deployment implements it? What changes if one of these relationships’ changes? That is API landscape knowledge. This is also why graph-based approaches become interesting. Not because a graph database magically solves architecture, but because relationships become explicit rather than remaining scattered across documents, repositories and platforms. An API then stops being only an endpoint, a specification or a catalog entry. It becomes part of an observable landscape.

The six LinkedIn articles started with different API questions. They end at the same point:

The API itself is not the boundary of the knowledge we need to understand it.