Document the whole API lifecycle

An endpoint schema tells you how to send a request. It rarely tells you what to do when the connection closes before a response arrives. AntAPI's documentation separates generated API Reference pages from integration guides so that both questions have a place.

Start with a capability, then explain its lifecycle

The API Reference describes published methods, paths, parameters, and response fields. Product pages explain what a capability is useful for. The guides connect those details into an application workflow: authenticate, submit work, preserve its identity, retrieve the result, and understand settlement.

WHOIS makes that distinction concrete. A single lookup returns a registration result. A batch submission returns a job identity, followed by progress checks and paginated results. Treating the submission's HTTP 202 as completion would leave both the integration and its billing explanation unfinished.

Acceptance, execution, and settlement are different events

For an asynchronous paid operation, the Gateway reserves the authorized maximum before execution. The platform later verifies the final successful quantity, debits that portion, and releases the rest. Progress checks, existing result reads, cancellation, and TLD support queries are free WHOIS operations, while still requiring authentication.

The useful success definition belongs beside that workflow. WHOIS counts both registered and conclusively unregistered results. An unknown outcome is not a conclusive answer. Duplicate normalized domains within a batch share processing; cancellation does not erase already successful work.

These distinctions matter when implementing an interface as much as when reading a receipt. A UI should show that a job has been accepted without implying that all items succeeded or that a reservation is already a final charge.

Make recovery part of the example

A batch example needs an idempotency key saved before submission, a job ID saved afterward, and an explanation of what happens if either response is lost. Reusing the original key recovers the same logical operation. Generating a fresh key can create a second job.

The same discipline keeps documentation safe to copy: all calls go through the configured Gateway, secrets stay in a trusted server environment, and examples avoid invented prices or universal limits.

The quickstart introduces the first request. The batch guide and billing guide cover the rest of the lifecycle. They accompany the generated reference rather than duplicating its schemas.