How do you document an API integration?

Direct answer

What a strong answer covers

How it works

An integration document is what lets two teams build against each other without a meeting per field. It lists each operation with its purpose, request and response schemas with types, required fields, formats, and examples, and the validation rules that produce each error. It states how the caller authenticates, what it is authorised to see, whether operations are idempotent and how, how lists paginate, what status codes and error bodies mean, what rate and size limits apply, how the contract is versioned, and what timeouts and retry behaviour the caller should adopt. Machine-readable OpenAPI with prose for the parts a schema cannot express is the usual form.

Example

The shipment API document showed POST /shipments with a JSON schema, an example payload, the Idempotency-Key requirement, a 409 for duplicate tracking numbers with a body example, cursor pagination on GET /shipments, a 120 requests per minute limit with the headers that report it, and the recommendation to retry only 503 with exponential backoff. The partner integrated in a week with two questions instead of the usual twenty.

Common mistakes

• Documenting the happy-path response only and leaving errors undefined.
• Publishing field names without types, formats, or which are required.
• Letting the document drift from the implementation because nothing checks it.

A useful answer structure

Answer from your own work.

Do not memorise a script: use only examples you can explain honestly in follow-up questions.