# API review checklist

## Model

- [ ] Do resource names match user vocabulary rather than table names?
- [ ] Can a typical screen be served without more than two or three calls?
- [ ] Is one relationship style used consistently throughout?

## Naming

- [ ] One casing convention, no exceptions?
- [ ] Collections plural, members singular?
- [ ] Any verbs in paths that should be methods?
- [ ] Any name that encodes a current implementation detail?

## Errors

- [ ] Stable error code on every error, separate from the status?
- [ ] Does each message say what the client should do?
- [ ] Do validation errors identify the offending field?
- [ ] 401 versus 403 used correctly?
- [ ] Any 200 response carrying an error?
- [ ] Any internal detail exposed in an error body?

## Collections

- [ ] Pagination on every list, including short ones?
- [ ] Cursor-based where the underlying data changes?
- [ ] Maximum page size documented and enforced?
- [ ] Filter and sort parameters finite and documented?

## Evolution

- [ ] Is the versioning strategy written down?
- [ ] Is every required field genuinely required forever?
- [ ] Is enum extensibility documented?
- [ ] Would adding a field break a well-behaved client?

## Permanent details

- [ ] Timestamps ISO 8601 with offset?
- [ ] Money in integer minor units with a currency?
- [ ] Identifiers opaque?
- [ ] Null versus absent documented?
- [ ] Idempotency key on retryable unsafe methods?
- [ ] Rate limits documented, with headers?

## Documentation

- [ ] Does every endpoint have a real example request and response?
- [ ] Are the error cases documented, not just the success case?
- [ ] Could someone integrate from the docs alone, without reading the source?