API Design

REST API Design Rules

1. URL Design

Basic Principles

• Use nouns, not verbs, to represent resources
• Use plural forms instead of singular
• Use kebab-case for URL paths (lowercase with hyphens)
• Represent hierarchical relationships in the URL structure

URL Patterns

# Resource collection
GET    /users                  # List users
POST   /users                  # Create user

# Specific resource
GET    /users/{id}             # Get specific user
PUT    /users/{id}             # Full update
PATCH  /users/{id}             # Partial update
DELETE /users/{id}             # Delete user

# Sub-resources
GET    /users/{id}/orders      # List user's orders
POST   /users/{id}/orders      # Create order for user
GET    /users/{id}/orders/{orderId}  # Get specific order

# Actions (when noun representation is difficult)
POST   /users/{id}/password-reset   # Reset password
POST   /orders/{id}/cancel          # Cancel order

Anti-Patterns

# Bad examples
GET    /getUsers
POST   /createUser
DELETE /deleteUser/123
GET    /user              # singular form
GET    /Users             # uppercase
GET    /user_orders       # snake_case

# Good examples
GET    /users
POST   /users
DELETE /users/123

2. HTTP Methods

Method Usage

Idempotency

• Idempotent: Multiple identical requests produce the same result
• GET, PUT, DELETE must guarantee idempotency
• POST is not idempotent → duplicate creation prevention logic required

3. HTTP Status Codes

Success (2xx)

Redirection (3xx)

Client Errors (4xx)

Server Errors (5xx)

4. Request/Response Format

Request Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
X-Request-ID: <uuid>

Response Format - Success

{
  "data": {
    "id": "user-001",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:45.123Z",
    "requestId": "abc-123"
  }
}

Response Format - List

{
  "data": [
    { "id": "user-001", "name": "John Doe" },
    { "id": "user-002", "name": "Jane Doe" }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "perPage": 20,
    "totalPages": 5
  }
}

Response Format - Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:45.123Z",
    "requestId": "abc-123"
  }
}

5. Pagination

Pagination Strategy Selection

6. Filtering, Sorting, Field Selection

# Filtering
GET /users?status=active&role=admin

# Sorting
GET /users?sort=-createdAt         # descending
GET /users?sort=name,-createdAt    # multiple sort

# Field Selection
GET /users?fields=id,name,email

7. API Versioning

See references/versioning.md for detailed patterns including:

• Version identification strategies (URL, Header, Custom)
• Compatibility principles (safe vs breaking changes)
• Handling breaking changes and deprecation

8. Security

• All APIs must be served over HTTPS only
• Never include sensitive data in URLs — use request body
• Implement rate limiting with X-RateLimit-* headers

9. Documentation

See references/documentation.md for detailed patterns including:

• OpenAPI specification structure
• Schema and parameter documentation
• Error response documentation
• Authentication documentation

10. References

• Semantic Versioning Specification — Industry standard for version numbering
• RFC 7231 (HTTP/1.1 Semantics and Content) — HTTP methods and content negotiation
• RFC 8594 (The Sunset HTTP Header Field) — API deprecation notification standard
• Microsoft REST API Guidelines - Versioning — Large-scale API versioning practices
• Google Cloud API Design Guide — API compatibility and versioning guide
• Pact Contract Testing — Consumer-Driven Contract Testing framework

Related Skills

• For OpenAPI specification writing and schema design, see openapi-spec skill