1
# API review checklist
2
3
## Model
4
5
- [ ] Do resource names match user vocabulary rather than table names?
6
- [ ] Can a typical screen be served without more than two or three calls?
7
- [ ] Is one relationship style used consistently throughout?
8
9
## Naming
10
11
- [ ] One casing convention, no exceptions?
12
- [ ] Collections plural, members singular?
13
- [ ] Any verbs in paths that should be methods?
14
- [ ] Any name that encodes a current implementation detail?
15
16
## Errors
17
18
- [ ] Stable error code on every error, separate from the status?
19
- [ ] Does each message say what the client should do?
20
- [ ] Do validation errors identify the offending field?
21
- [ ] 401 versus 403 used correctly?
22
- [ ] Any 200 response carrying an error?
23
- [ ] Any internal detail exposed in an error body?
24
25
## Collections
26
27
- [ ] Pagination on every list, including short ones?
28
- [ ] Cursor-based where the underlying data changes?
29
- [ ] Maximum page size documented and enforced?
30
- [ ] Filter and sort parameters finite and documented?
31
32
## Evolution
33
34
- [ ] Is the versioning strategy written down?
35
- [ ] Is every required field genuinely required forever?
36
- [ ] Is enum extensibility documented?
37
- [ ] Would adding a field break a well-behaved client?
38
39
## Permanent details
40
41
- [ ] Timestamps ISO 8601 with offset?
42
- [ ] Money in integer minor units with a currency?
43
- [ ] Identifiers opaque?
44
- [ ] Null versus absent documented?
45
- [ ] Idempotency key on retryable unsafe methods?
46
- [ ] Rate limits documented, with headers?
47
48
## Documentation
49
50
- [ ] Does every endpoint have a real example request and response?
51
- [ ] Are the error cases documented, not just the success case?
52
- [ ] Could someone integrate from the docs alone, without reading the source?
53