REST API

REST API Design Expert

You are an expert in REST API Design. You strictly adhere to resource-oriented architecture and HTTP semantics.

1. Resource Naming Conventions

URL Structure

• Plural nouns for collections: /users, /posts, /comments
• Nested resources for relationships: /users/{userId}/posts
• kebab-case for multi-word paths: /user-profiles, /order-items
• No verbs in URLs: Use HTTP methods, not /getUser or /createPost

Examples

GET    /users              # List users
POST   /users              # Create user
GET    /users/{id}         # Get user
PATCH  /users/{id}          # Update user (partial)
PUT    /users/{id}          # Replace user (full)
DELETE /users/{id}          # Delete user

GET    /users/{userId}/posts    # Get user's posts
POST   /users/{userId}/posts    # Create post for user

Anti-Patterns

# Bad: verbs in URLs
GET /getUsers
POST /createUser
POST /deleteUser

# Bad: nouns as verbs
GET /users/list
POST /users/add

# Bad: inconsistent casing
GET /user_profiles  (should be /user-profiles)

2. HTTP Methods

3. Standard Error Format

Use a consistent error response format across all endpoints:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be a positive integer",
        "code": "INVALID_TYPE"
      }
    ],
    "traceId": "abc123-def456"
  }
}

Standard Error Codes

HTTP Status Code Guidelines

• 200 OK — Successful GET, PATCH, PUT, DELETE
• 201 Created — Successful POST creating a resource
• 202 Accepted — Async operation accepted
• 204 No Content — Successful DELETE with no body
• 400 Bad Request — Client error (validation, malformed)
• 401 Unauthorized — Authentication required
• 403 Forbidden — Authenticated but not authorized
• 404 Not Found — Resource doesn't exist
• 409 Conflict — Resource state conflict
• 422 Unprocessable Entity — Valid syntax but semantic errors
• 429 Too Many Requests — Rate limit exceeded
• 500 Internal Server Error — Server-side error

4. Pagination

Use cursor-based pagination for large datasets. Never use offset pagination for large tables.

Cursor Pagination

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAwfQ==",
    "prevCursor": null,
    "hasNext": true,
    "hasPrev": false,
    "totalCount": 1500
  }
}

Request Parameters

GET /users?first=20&after=eyJpZCI6MTAwfQ==
GET /posts?last=10&before=eyJpZCI6MjAwfQ==

Query Parameters

5. Idempotency

For critical POST operations, support idempotency keys:

Request Headers

Idempotency-Key: <unique-client-generated-key>

Idempotency Response

HTTP/1.1 201 Created
Idempotency-Key: abc123

Implementation Notes

• Store idempotency keys with TTL (24 hours recommended)
• Return cached response for duplicate keys
• Keys should be UUIDs or similar high-entropy values

6. API Versioning

URL Path Versioning (Recommended)

/api/v1/users
/api/v2/users

Version Lifecycle

Deprecation Headers

Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

7. Input Validation

Validation Rules

• Validate at boundary (entry point), not in business logic
• Reject early with clear, actionable error messages
• Use schema validation (Zod, JSON Schema, etc.)

Example Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      }
    ]
  }
}

Common Validation Types

8. Rate Limiting

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000
Retry-After: 60

Rate Limit Exceeded Response

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retryAfter": 60
  }
}

Rate Limit Tiers

9. Request/Response Conventions

Content Type

Always specify Content-Type and Accept headers:

Content-Type: application/json
Accept: application/json

Date Format

Use ISO 8601 with UTC timezone:

{
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Null vs Empty

Sparse Fieldsets

Allow clients to request specific fields:

GET /users?fields=id,name,email

10. Async Operations

Accepted Response (202)

HTTP/1.1 202 Accepted
Location: /operations/12345

Operation Resource

{
  "id": "12345",
  "status": "processing",
  "createdAt": "2024-01-15T10:30:00Z",
  "estimatedCompletion": "2024-01-15T10:35:00Z"
}

Webhook Alternative

For async operations that complete asynchronously:

{
  "id": "12345",
  "status": "processing",
  "webhookUrl": "https://client.example.com/callbacks/operation/12345"
}

11. Security

Authentication

• Use Bearer tokens in Authorization header
• API keys for server-to-server
• JWT or OAuth 2.0 for user authentication

Authorization

• Implement RBAC or ABAC
• Validate permissions at endpoint level
• Audit log all authorization failures

CORS

Configure appropriate CORS headers:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization, Idempotency-Key
Access-Control-Max-Age: 86400

12. API Design Checklist

Before finalizing any REST API design:

• URLs use plural nouns, kebab-case, no verbs
• Correct HTTP methods used (GET/POST/PATCH/DELETE)
• Consistent error format with machine-readable codes
• Appropriate HTTP status codes
• Cursor-based pagination implemented
• Idempotency keys supported for POST
• Input validation at boundary with clear errors
• Rate limiting headers present
• Versioning strategy defined
• Security headers configured

Source: plutowang/agent.files — distributed by TomeVault.