Interview prompt
Explain designing apis around explicit semantics to an engineer who understands the surrounding system but has not used this technique. Walk from its contract to a concrete operation, then discuss where it fails or becomes expensive.
A strong answer
An API contract defines the meaning of operations, inputs, outputs, errors, and side effects. A good contract lets clients reason about retries and compatibility without depending on undocumented server behavior. HTTP methods communicate broad intent, while the application contract defines the resource-specific rules.
A PUT that replaces a resource can be retried safely when the same request produces the same target state. A POST that creates a payment may create duplicates unless the server recognizes an idempotency key. A response should distinguish validation failures, authorization failures, and transient server problems.
A complete answer also calls out the assumptions that control correctness. Backward compatibility includes behavior as well as field names: changing default ordering or error semantics can break clients. Adding an optional field is often safer than changing a required one, but strict client decoders may still reject it. Version only when compatibility policy and migration need justify it.
Close by describing one representative test or measurement. An endpoint creates an invoice but the client times out before receiving the response. Specify a request and storage design that lets the client retry without creating a second invoice.
Follow-up questions
Answer the follow-ups in the frontmatter. Use the linked article for the concept and the trace to make the explanation concrete.