Documentation is part of discovery.
Teams sometimes treat API documentation as implementation material for developers. I think it belongs much earlier. If the proposed design depends on an endpoint, event model, identity rule or rate limit, those constraints can change the architecture before anyone writes code.
The pages I care about first.
- Authentication: how credentials are scoped, rotated and separated by environment.
- Identity: which identifier is authoritative, whether anonymous and known profiles can merge, and what happens when identifiers change.
- Request limits: payload size, batch size, rate limits and concurrency behaviour.
- Error semantics: what a 200 actually means, which failures are retriable, and whether accepted requests can still fail later.
- Data model: events versus attributes, required fields, timestamps and idempotency expectations.
- Operational behaviour: logging, retries, webhooks, async processing and observability.
Questions I want answered before build.
The payoff is not just fewer bugs.
Early documentation review makes requirements better. It exposes questions the business may not know to ask, gives engineering clearer acceptance criteria and helps the delivery team distinguish a platform constraint from an implementation choice.
It also makes trade-offs easier to explain. “The API cannot do that” and “we chose not to do that” are very different conversations.
Worked example · October 9, 2026
Turn the contract into tests.
Waypoint’s local mock adapter distinguishes a rate-limit response, a transient failure, a non-retryable error and a 200 response with record errors. It honors a short server wait and defers a longer one instead of shortening it. This adapter is illustrative: a live integration must read the endpoint’s actual error body, rate-limit scope and retry rules before implementing recovery.
Fictional local exercise; no live vendor or client outcome is asserted.