The shape of a production API is defined by its bad days

An API contract includes the request shape, response shape, validation rules, error codes, pagination, authentication, and what happens when the same request is sent twice. Documenting only a successful JSON example leaves the integrating team to discover the important parts in production.

Names matter because they become long-lived dependencies. A field called status needs an allowed-value list and clear transitions. A date needs a timezone rule. An optional field needs a defined meaning when it is absent. Precise contracts reduce support work far more effectively than a clever implementation detail.

Networks retry. Browsers retry. People double-click. A create or payment-style operation should not produce a second record simply because the client did not receive the first response. Idempotency keys, unique business identifiers, and careful transaction boundaries give the server a way to recognise a repeat request.

This is not only a payment concern. It applies to imports, notification dispatch, inventory updates, and webhook consumers. The safe result is either the original completed operation or a clear conflict, never a silent duplicate.

When a customer says a request failed, a useful system can trace it from the public request ID to validation, upstream calls, storage, and the final response. Structured logs with a correlation ID make that possible without dumping private data into log files.

Metrics should answer boring operational questions quickly: how many requests fail, which dependency is slow, how long a queue has been waiting, and whether retries are growing. An API does not become production-ready at build time. It becomes production-ready when someone can diagnose it at 2 a.m. without guessing.