Step-by-step checklist for designing REST APIs: naming conventions, versioning, pagination, filtering, error format, authentication, and rate limiting.
Step-by-step checklist for designing REST APIs: naming conventions, versioning, pagination, filtering, error format, authentication, and rate limiting.
BeforeMerge offers hundreds of code review rules, guides, and detection patterns to help your team ship better code.
Use this runbook when designing a new REST API or auditing an existing one.
/users not /getUsers/users, /orders/users/:id/orders/users/:id/orders (not /users/:id/orders/:id/items/:id)/user-profiles not /userProfiles| Method | Purpose | Idempotent | Body |
|---|---|---|---|
| GET | Read | Yes | No |
| POST | Create | No | Yes |
| PUT | Full replace | Yes | Yes |
| PATCH | Partial update | Yes | Yes |
| DELETE | Remove | Yes | No |
/v1/users (simplest, most common)Accept: application/vnd.api+json;version=1{
"data": [...],
"pagination": {
"cursor": "eyJpZCI6MTAwfQ==",
"has_more": true,
"total": 1234
}
}?status=active&role=admin?sort=created_at&order=desc?fields=id,name,email{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"details": [
{ "field": "email", "message": "must not be empty" }
]
}
}Authorization: Bearer <token>X-RateLimit-Limit: 100X-RateLimit-Remaining: 95X-RateLimit-Reset: 1620000000Content-Type: application/jsonLocation header