API Design Standards — Versioning, Errors & Webhooks
Our house standard for REST APIs: resource naming, error envelopes, idempotency, and webhook delivery.
1. Resources & Versioning
Nouns, not verbs: /orders not /createOrder. Nest one level deep maximum; deeper nesting becomes unmaintainable. Version in the path (/v1/) from day one — header versioning confuses every consumer.
Pagination is cursor-based for large collections, offset only for admin UIs under 10k rows. Every list response includes total counts and rate-limit headers.
2. Errors & Idempotency
One error envelope everywhere: machine-readable code, human message, request ID, and docs link. Never leak stack traces or SQL to clients.
Mutating endpoints accept idempotency keys. Retries are safe by construction — the foundation of reliable payments and webhook handlers.
3. Webhooks Consumers Love
Sign every payload (HMAC), include event IDs and timestamps, and retry with exponential backoff for 24 hours. Provide a dashboard showing delivery history per endpoint.
Version webhook payloads independently from the API, and never remove fields — only deprecate with 6-month notice.
Frequently asked questions
REST or GraphQL?
REST for partner APIs and webhooks; GraphQL for complex frontend data needs. Most products need REST first.
How do you document APIs?
OpenAPI generated from code, published to a developer portal with runnable examples and a Postman collection.