API Contracts & Data Models

Foundations

An interface is the contract between callers and a system: for each operation, its method, path, request body, success response, and failure responses. A data model is the rows that contract reads and writes, with a primary key and any uniqueness rules. Writing both before the diagram shows what each call costs: a read by primary key, a join, or a write on the hot path.

Design the hottest call first and keep it cheap: one indexed read by its key, with no join and no write. Status codes are part of the contract, such as 201 created, 404 not found, and 409 conflict, because callers act on them. Anything the hot call does not need stays off its row, so the read stays cheap and cacheable.

Take an item service: POST /items returns 201 with the new id, or 409 if a chosen name is taken, and GET /items/{id} returns 200, or 404 for an unknown id. The row is keyed by id, with name unique. A view_count column would turn every GET into a write, so views get their own path.

• Requirements

  Estimates and APIs start from an agreed list of what the system must do.

  Open lesson

Case Scenario

To see how an API contract keeps the hottest call cheap, consider a URL shortener like bit.ly: an owner creates a short code for a long URL, optionally a custom alias, and visitors open that code to be redirected. POST /links returns 201 or 409; GET /{code} returns 301 or 404, one primary-key read with no join.

A shortener has two callers with different outcomes: an owner creates a code, and a visitor opens it. Alias conflicts, missing codes, and expired links must be unambiguous before components are chosen, or hidden work appears on the busiest call. The contract must keep each redirect to one lookup, with no join, while preserving unique aliases and expiry.