APIs Are Contracts · Product Fluency

APIs Are Contracts · 4 min

Situation

The interface needs something the API cannot supply.

Design proposes filtering orders by delivery date. Engineering says, “The API doesn't support that.” This could mean the field is absent, the filter is unavailable, the data is owned elsewhere, or the endpoint cannot perform at the required scale.

Do not jump directly to “Can we do it in the frontend?” First identify the missing capability.

Mental model

A contract connects independent parts.

An endpoint is an address for an operation or resource. The request specifies inputs. The response describes outputs. A schema defines expected fields and types.

The full contract also includes permissions, errors, limits, latency expectations, and compatibility. Ownership matters because another team or vendor may control changes to that contract.

Example · Request

Ask for a page of shipped orders.

GET /orders?status=shipped&limit=20

The client requests shipped orders, with at most 20 results in this page. The contract supports a status filter. It does not establish that filtering by delivery date is available.

The next screen shows the response this request could return.

Example · Response

Read what comes back.

{
  "orders": [
    {
      "id": "o_17",
      "status": "shipped"
    }
  ],
  "next_cursor": "page_2"
}

The cursor allows another page of results. This response does not establish that delivery dates exist or are current, or that downloading every order to filter locally is safe.

Ask engineering

Locate the actual constraint.

“Is the data missing, or is querying it unsupported? Who owns the data and endpoint? Is delivery date estimated or confirmed? What are the volume and freshness requirements?”

Then ask about options: extending the endpoint, using another source, changing the interaction, or narrowing the initial scope. Ask for trade-offs before assigning an implementation.

Failure case

Breaking a client you did not know existed.

Changing a response field from a number to a string may break a mobile app, integration, or customer script. Renaming a field without a migration path can turn an internal cleanup into a product incident.

Versioning and deprecation give clients time to adapt. Even additive changes deserve thought if older clients assume a closed list of values or fixed response size.

Product decision

Make the dependency visible in the plan.

Suppose another team can add delivery filtering in three weeks. You could delay the feature, launch a narrower status filter, or temporarily link to an existing operations view.

Do not promise the richer interaction while treating the API change as a minor follow-up. Record the owner, agreed contract, test data, and what happens if the dependency slips.

Think it through

What would you put in acceptance criteria?

Specify which users may filter which orders, how unknown delivery dates behave, how results are paginated, and what the interface shows when the service is unavailable.

Ask the team to test the consumer against realistic responses before the production integration is complete. A mock can reveal misunderstandings but cannot prove real performance.

Remember this

An API limitation is a product constraint to clarify.

Your role is to explain the needed outcome, understand the contract and its owner, and choose among feasible experiences. You do not need to design the endpoint alone.