REST API Design Checklist | BeforeMerge | BeforeMerge

REST API Design Checklist

Use this runbook when designing a new REST API or auditing an existing one.

1. URL Structure

Use nouns, not verbs: /users not /getUsers
Use plural nouns: /users, /orders
Nest for relationships: /users/:id/orders
Limit nesting to 2 levels: /users/:id/orders (not /users/:id/orders/:id/items/:id)
Use kebab-case: /user-profiles not /userProfiles

2. HTTP Methods

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

3. Versioning

Choose a strategy and be consistent:
- URL prefix: /v1/users (simplest, most common)
- Header: Accept: application/vnd.api+json;version=1
Never break existing versions
Document deprecation timeline

4. Pagination

Choose cursor-based (preferred) or offset-based
Return pagination metadata

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true,
    "total": 1234
  }
}

Set a max page size (e.g., 100)
Default to a reasonable size (e.g., 20)

5. Filtering and Sorting

Use query parameters: ?status=active&role=admin
Support sorting: ?sort=created_at&order=desc
Support field selection: ?fields=id,name,email
Document all supported filters

6. Error Format

Use consistent error structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [
      { "field": "email", "message": "must not be empty" }
    ]
  }
}

Map errors to correct HTTP status codes
Never expose stack traces in production
Include a request ID for debugging

7. Authentication

Use Bearer tokens: Authorization: Bearer <token>
Return 401 for missing/invalid auth
Return 403 for insufficient permissions
Document auth requirements per endpoint

8. Rate Limiting

Set rate limits per endpoint or tier
Return rate limit headers:
- X-RateLimit-Limit: 100
- X-RateLimit-Remaining: 95
- X-RateLimit-Reset: 1620000000
Return 429 when exceeded

9. Response Standards

Always return JSON with Content-Type: application/json
Use 201 for created resources with Location header
Use 204 for successful deletes (no body)
Include timestamps in ISO 8601 format
Use consistent casing (camelCase or snake_case — pick one)

REST API Design Checklist

Related

Explore more rules and knowledge

REST API Design Checklist

1. URL Structure

2. HTTP Methods

3. Versioning

5. Filtering and Sorting

6. Error Format

7. Authentication

8. Rate Limiting

9. Response Standards