APIs Expose Data, Not Meaning

The previous article drew a line from SOA to the present. Structural contracts were never enough, because they defined how services communicated, not what they meant.

Agents push that gap into the foreground.

This article is about what the gap looks like in practice, and why it is harder to close than it appears.

The Schema Isn’t The Contract

When we talk about API quality, we tend to talk about schemas.

Is the response well structured? Are the types correct? Is the contract versioned? Is there an OpenAPI specification? These things matter. They are part of the discipline. But they are not the whole contract.

A schema defines shape. It does not define meaning.

That difference is easy to miss when the consumer is a human developer. Developers read documentation, ask questions, infer context, and notice when something does not behave as expected. They build a mental model of the system over time. The API may be incomplete, but the human fills in some of the missing meaning.

Agents do not have that same feedback loop. They operate on what is exposed. If what is exposed is structurally valid but semantically ambiguous, the result can be plausible and wrong at the same time. Worse, it can be wrong consistently, at speed, and without anyone noticing until a decision has already been made.

A Field Called Gender

Take a field that appears in many enterprise systems: gender.

It looks straightforward. The schema validates. Values come back as M, F, or perhaps Other. There are no errors, no failed calls, and nothing obviously broken in the payload.

But which gender is it?

In an HR system, it may be the employee’s self-reported gender identity, used for inclusion reporting and pronoun preferences in internal tooling. In a payroll system, it may be the legal sex recorded on government tax documents, constrained by statutory reporting requirements. In a healthcare benefits platform, it may represent biological sex for insurance categories, clinical screening, or medication rules. In a CRM, it may not be identity at all, but an inferred marketing segment derived from behavioural signals.

The field name is the same. The values may look similar. The meaning is not the same.

That difference is not pedantry. It changes governance, privacy, acceptable use, and the decisions that can safely be made from the value. An agent composing across these systems does not just risk getting the value wrong. It risks using the right value in the wrong context, which is often more dangerous.

A value that is accurate in one domain can produce a decision that is structurally sound and substantively incorrect in another.

The API exposed data. It did not expose meaning.

The Same Problem Appears Everywhere

The gender example is vivid, but it is not unusual. Most large organisations have the same problem in less sensitive and less obvious forms.

A field called status might describe whether a customer is active, whether an account is billable, whether a workflow has completed, or whether access should be allowed. A field called type might represent a product category in one system, a regulatory classification in another, and an internal routing hint somewhere else. The schema may be valid in each case, but the semantics do not travel cleanly between systems.

Dates create a similar problem in a less sensitive but very familiar form. I have seen APIs where the date format was perfectly defined, but a business convention sat outside the schema: a timestamp with the time set to midnight meant “this is a whole-day value”, not “this happened at exactly midnight”. Structurally, the value was valid. Semantically, it carried an assumption the caller had to know.

That kind of convention causes real problems downstream, especially in analytics. If one system uses midnight to mean “no time component”, another uses it as an actual event time, and a third applies local business-day rules, then a simple question like “show me everything for Tuesday” stops being simple. The data shape is consistent. The meaning is not.

The same issue applies to operations. An endpoint called updateCustomer may sound simple, but what does it actually do? Does it only change a record? Does it trigger a notification? Does it alter audit state? Does it start a downstream workflow? Does it have different behaviour depending on who called it, which channel the request came from, or which state the customer is already in?

These are not edge details. They are part of the real contract.

The missing meaning sits in several places at once: field semantics, operation intent, domain context, provenance, side effects, idempotency, consistency, ordering, and authority. Some of that can be documented. Some of it needs to be designed into the API surface. Some of it belongs in governance and access control. But it cannot be left as tribal knowledge if the caller is an agent.

Why We Got Away With It

Human developers are good at closing semantic gaps.

They read between the lines. They ask for clarification. They test unexpected cases. They learn which systems are reliable, which fields are overloaded, which APIs are safe to compose, and which ones require care. Over time, that knowledge becomes distributed across teams, conventions, runbooks, and the memory of people who have integrated with the system before.

It is slow and fragile, but it works up to a point.

What it really means is that the full contract was never in the API. It was partly in the schema, partly in the documentation, partly in the code that called it, and partly in the institutional knowledge around the system.

Agents inherit very little of that.

They do not know which field is politically sensitive, which status value is overloaded, or which endpoint has a side effect that everyone on the team remembers but nobody put in the schema. When the formal contract is incomplete, they fill the gap with inference.

Inference from incomplete contracts is where the risk concentrates.

Better Semantics Is Not Just More Documentation

The obvious response is to document more. That helps, but it is not enough.

If meaning sits only in prose beside the API, it is still separate from the thing being called. A human may read it. A generated client may ignore it. An agent may summarise it incorrectly, overweight the wrong part, or fail to connect it to the specific operation being performed.

Richer semantics has to affect the design of the API itself.

That means names should reflect business intent rather than implementation convenience. approveClaim, suspendAccount, or issueRefund carry more meaning than a generic update operation with a status field buried in the payload. Enumerated values should describe what they mean, not just which strings are valid. Side effects should be explicit at the point of call. Provenance and governance context should be part of what is exposed when the meaning of a value depends on where it came from.

It also means separating concepts that only look similar. If legal sex, gender identity, biological sex, and marketing inference mean different things, they should not collapse into one generic field just because the values happen to overlap. If customer status means different things in billing, fulfilment, support, and access control, the API should not pretend there is one universal truth called status.

That is not just better schema design. It is domain modelling.

The Real Question

If SOA taught us that structural contracts are not enough, and the semantic gap shows us that data without meaning is not a complete contract, then the next question is straightforward.

What would an API look like if it were designed from the start to carry meaning, not just data?

Not a larger schema. Not a thicker PDF beside the endpoint. A different model of the API itself: one where business capability, domain intent, authority, provenance, and behavioural guarantees are first-class concerns rather than things the consumer has to reconstruct from structure alone.

That is what an agent-ready API requires.

It is also a much richer definition of an API than the technical contract we have been working with.