API contracts that survive imperfect clients

A schema can say that a field is a number without saying whether it measures seconds, milliseconds, or a probability. Document units, bounds, required fields, nullability, and unknown-field behavior. For inference, define accepted input size and encoding, model identity, and output interpretation. A score is not automatically a calibrated probability. A well-formed response can still violate the domain meaning the caller relied on.

Validation belongs at a boundary where assumptions change. Reject malformed or unsupported input with useful, stable error information, while avoiding leaks of internal state or sensitive data. Authentication identifies a principal; authorization determines what that principal may do. Successful schema validation supplies neither. Describe these responsibilities explicitly instead of treating every failure as a generic server error or expecting generated client types to enforce runtime values.

An idempotent operation has the same intended effect when applied repeatedly as when applied once. That does not require identical response bodies, and it does not guarantee that only one internal execution occurs. For a job-creation API, an application can define a client-supplied operation key and store its associated request and result. A retry with the same key can then refer to the same logical submission.

Such a policy needs details: key scope, retention duration, concurrent duplicates, and behavior when a key is reused with different content. Persisting the key separately from the effect can leave a failure gap, so the implementation needs an appropriate atomicity story. Do not advertise exactly-once business outcomes merely because a header exists. State which repeated effects the contract prevents and which failures still require reconciliation.

Adding an optional field is often easier to accommodate than removing a required one, but compatibility depends on consumer behavior. A client that rejects unknown fields can break on an addition. A changed default, ordering, precision, or error code can break a consumer without changing the JSON shape. Contract tests should cover documented examples and critical invariants across producer and consumer versions rather than simply checking that a document parses.

Use an API description to make operations discoverable, then keep it consistent with running behavior. The lab isolates the load side of retries. Increase arrival rate while keeping service rate fixed and watch the fluid backlog. Compare this with the extra attempts in the equation above. This queue does not validate schemas, enforce deadlines, deduplicate operations, or generate retries automatically. The separate M/M/1 residence-time readout requires its stochastic assumptions; the fluid animation alone does not establish production latency.