Field notes / OpenAPI

OpenAPI review checklist before you share with a partner

1. Info block: Contact email, version policy, and base URL for sandbox vs production.
2. Security schemes: Every operation tagged; example curl for token exchange.
3. Examples: At least one realistic payload per write operation—real field lengths, ZA phone formats where relevant.
4. Error responses: Shared schema referenced on all 4xx/5xx; no empty 400 bodies.
5. Pagination: Parameters documented with defaults and max limits.
6. Idempotency: Header documented on POST that creates billing or inventory records.
7. Webhooks: If async, separate path document or asyncAPI appendix with retry rules.
8. Changelog: Link to dated changes integrators must read before upgrading.

Run this list in a 60-minute internal meeting with someone who will not implement the API—product or support often spots ambiguous nouns first.