Good API design saves everyone time. Go through this checklist before publishing your API.
Naming & Structure¶
- ☐ Resources as nouns (/users, /orders)
- ☐ Plural consistently
- ☐ Hierarchical URLs (/users/123/orders)
- ☐ Kebab-case for multi-word
- ☐ Versioning (v1/users or Accept header)
HTTP Methods¶
- ☐ GET = reading (idempotent)
- ☐ POST = creation
- ☐ PUT = full update
- ☐ PATCH = partial update
- ☐ DELETE = deletion
Response¶
- ☐ Consistent response format
- ☐ Proper status codes
- ☐ Pagination (limit/offset or cursor)
- ☐ Filtering and sorting parameters
- ☐ HATEOAS links (optional)
Error Handling¶
- ☐ Structured error response { code, message, details }
- ☐ Validation errors with field-level details
- ☐ No stack traces in production
- ☐ Rate limit headers (X-RateLimit-*)
Security¶
- ☐ Authentication (Bearer token / API key)
- ☐ Authorization on every endpoint
- ☐ Input validation and sanitization
- ☐ CORS properly configured
- ☐ Rate limiting
Documentation¶
- ☐ OpenAPI/Swagger spec
- ☐ Examples for every endpoint
- ☐ Error catalog
- ☐ Getting started guide
Tip¶
Design APIs from the consumer’s perspective, not the implementation. And always write an OpenAPI spec.
apirestdesign