API Design
An API is a contract between independently changing systems.
Design around
- Resources/actions and stable domain language
- Explicit schemas and validation
- Authentication versus per-resource authorization
- Idempotency for retried operations
- Pagination, filtering, ordering, and limits
- Consistent errors with machine-readable codes
- Versioning and backward-compatible evolution
- Rate limits, timeouts, observability, and documentation
Questions
- Can the client safely retry this request?
- How does absence differ from forbidden or invalid?
- What prevents one user accessing another user's object?
- What happens when client and server versions differ?
- Is sensitive data minimized in requests, responses, and logs?