APIs look like implementation details until other teams depend on them.

Then they become architecture.

The first article in this series covered the boundary lesson: expose the product concept, not the internal machinery. This article starts from there and asks a narrower question:

"What makes an API contract safe to depend on over time?"

That question is about versioning, errors, pagination, rate limits, ownership, and observability. Routes and payloads matter, but the deeper design is the promise the API makes to consumers.

The API Is The Contract Consumers Build Around

An API decides what other systems are allowed to know, rely on, retry, cache, paginate, display, and debug.

That makes the API contract larger than the route name and response shape.

It decides:

• which product concepts cross the boundary
• which errors consumers can act on
• which usage patterns are supported
• how compatibility is handled
• who owns the contract
• how consumers debug failures

The first article in this series showed the general boundary lesson: expose the product concept, not the internal machinery. In API design, that lesson becomes very practical because every field can become a commitment.

Suppose an order API exposes warehouse internals because the first consumer is an internal dashboard:

{
  "warehouseState": "PICK_BATCH_ASSIGNED",
  "pickBatchId": "pb_884",
  "carrierCode": "DHL_DE",
  "retryCount": 2
}

That may help one operational tool. It is a poor general product contract.

If a mobile app or partner integration starts depending on those fields, fulfillment internals are now part of the external system. A warehouse process change becomes an API migration.

A stronger contract exposes the stable product state:

{
  "orderId": "ord_123",
  "fulfillmentStatus": "preparing",
  "estimatedDeliveryDate": "2026-05-31",
  "canCancel": true
}

The internal states still exist. The API gives consumers the concept they should build around.

This is where API design becomes architecture. The question is not only "What data can we return?"

The better question is:

"What decision should the consumer be able to make from this response?"

If the consumer needs to show progress, expose a stable progress concept. If the consumer needs to decide whether a cancel button is allowed, expose canCancel. Do not force every consumer to reverse-engineer business rules from internal status names.

Error Models Are Architecture

Errors are part of the API contract.

A vague error makes every consumer invent its own interpretation.

{
  "error": "Something went wrong"
}

That response does not tell the consumer whether the request can be retried, whether the user can fix the problem, whether support should be contacted, or whether the backend is down.

A better error shape gives consumers enough structure to behave safely:

{
  "code": "PAYMENT_METHOD_DECLINED",
  "message": "The payment method was declined.",
  "retryable": false,
  "correlationId": "corr_7a91"
}

This does not mean every API needs a giant error taxonomy. It means errors should help consumers make decisions.

At architecture level, the questions are:

• which errors can be retried?
• which errors require user action?
• which errors indicate a system failure?
• which errors must support correlation across services?
• which error codes are stable contracts?

If those decisions are not made centrally, consumers will encode guesses.

Those guesses become part of the system.

Versioning Is A Change Strategy, Not A URL Shape

API versioning is often reduced to path style:

/v1/payments
/v2/payments

That is only the visible part.

The real question is how the system changes while consumers keep running.

Versioning has to answer:

• what changes are backward-compatible?
• how long do old versions stay supported?
• how do consumers learn about deprecation?
• how do we know who still uses an old field or endpoint?
• what happens when a mobile app or partner cannot upgrade quickly?
• what does rollback mean after a new API shape is used?

Sometimes adding a new field is enough. Sometimes a new endpoint is cleaner. Sometimes a new version is necessary. Sometimes the right answer is to support both shapes temporarily and measure adoption.

The mistake is treating versioning as a naming convention instead of a product and operations policy.

Pagination, Filtering, And Sorting Are Contracts Too

Small API details become big system constraints.

A list endpoint that starts like this may seem harmless:

GET /orders

It works while the customer has 20 orders. It becomes dangerous when the customer has 20,000.

Adding pagination later is possible, but consumers may already assume the endpoint returns everything. Internal tools may export from it. Mobile clients may render it directly. Background jobs may depend on the original behavior.

A better first version makes the boundary explicit:

GET /orders?limit=50&cursor=eyJvZmZzZXQiOjUwfQ

Pagination is not only a performance concern. It defines how consumers move through data.

Filtering and sorting have the same problem. If consumers can filter by any field, the API exposes storage assumptions. If sorting changes silently, users may see inconsistent results. If pagination is offset-based on a changing dataset, items may be skipped or repeated.

The architecture question is:

"What access pattern are we promising?"

That question matters more than the exact query parameter names.

Rate Limits Are Part Of The Product Boundary

Rate limits are often added after abuse or overload.

They should be part of the API contract earlier than that.

A rate limit says what kind of usage the API is designed to support. It protects the provider, but it also gives consumers a clearer operating model.

An API without limits invites accidental overload.

An API with unclear limits creates surprise failures.

A useful limit should answer:

• what is limited?
• who is limited: user, tenant, app, token, IP, or organization?
• what happens when the limit is reached?
• when can the consumer retry?
• how can the consumer monitor its usage?

For example:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716900000

This turns a failure into a contract.

The consumer still has to handle it. But the API gives enough information to behave responsibly.

APIs Need Ownership

An API with no owner becomes a shared hallway where everyone leaves things.

One team adds a field. Another adds a special-case status. A third changes error behavior. A fourth writes documentation that is correct for one client and wrong for another.

Eventually the API becomes hard to change because nobody can confidently say what it means.

API ownership should be clear:

• who approves contract changes?
• who owns backward compatibility?
• who monitors usage?
• who communicates deprecations?
• who handles consumer support?
• who decides when an endpoint can be removed?

This ownership does not have to be heavy. It does have to exist.

If an API is important enough for other teams to depend on, it is important enough to have an owner.

Observability Starts At The Contract

An API should make its behavior visible.

That does not only mean backend logs.

The contract should support debugging:

• correlation IDs
• stable error codes
• consumer or application identity
• endpoint and version metadata

If a consumer says, "Your API failed," the provider should be able to answer:

• which request?
• from which consumer?
• on which version?
• with which error code?
• was the dependency slow?
• did this affect one tenant or many?

If those questions cannot be answered, the API is not operable enough.

The full observability discussion belongs in the observability article. The API-specific decision is which diagnostic fields are part of the contract instead of hidden inside provider-only logs.

A Practical API Design Checklist

Before publishing an API contract, ask:

1. What product concept does this API expose?
2. Which internal details are intentionally hidden?
3. Which fields are compatibility commitments?
4. What errors can consumers act on?
5. What usage pattern does pagination or filtering promise?
6. How will old consumers keep working during change?
7. Who owns this contract after it ships?
8. How will deprecations be communicated and measured?
9. What rate limits or quotas define safe usage?
10. What observability exists by consumer, version, and tenant?
11. What would make this API hard to remove later?

These questions are not about making the API perfect.

They are about making the boundary honest.

Where To Go Deeper

The Mobile SDK Design series goes deeper into public API surface from the SDK side, where the API becomes code another developer imports.

Use that branch when the API contract is packaged into a client library and the developer experience becomes part of the product.

Summary

An API is not just a way to move data.

It is a boundary between teams, products, clients, and future changes.

Good API design gives consumers stable concepts, useful errors, safe evolution paths, clear ownership, and enough observability to debug the contract in production.

Bad API design leaks internal decisions until every consumer becomes coupled to implementation details.

That is why API design is architecture.