API Design

API Design

Overview

Standards and patterns for designing consistent, well-documented RESTful APIs. Covers naming, HTTP methods, error handling, status codes, and documentation requirements.

Key Concepts

Naming Conventions

• Plural nouns for resources: /users, /orders, /products
• Kebab-case for multi-word: /user-profiles
• Nest related resources: /users/{id}/orders
• Query params for filtering: /users?role=admin&active=true

HTTP Methods

| Method | Purpose | Idempotent | Response |

|--------|---------|------------|----------|

| GET | Read | Yes | 200 + body |

| POST | Create | No | 201 + body + Location |

| PUT | Replace | Yes | 200 + body |

| PATCH | Partial update | No | 200 + body |

| DELETE | Remove | Yes | 204 (no body) |

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}

Status Codes

• 200: Success — 201: Created — 204: No content
• 400: Bad request — 401: Unauthorized — 403: Forbidden
• 404: Not found — 409: Conflict — 422: Unprocessable
• 429: Rate limited — 500: Internal error

Decision Framework

| Scenario | Method | Path | Status |

|----------|--------|------|--------|

| List items | GET | /items | 200 |

| Get one item | GET | /items/{id} | 200 / 404 |

| Create item | POST | /items | 201 |

| Full update | PUT | /items/{id} | 200 / 404 |

| Partial update | PATCH | /items/{id} | 200 / 404 |

| Delete item | DELETE | /items/{id} | 204 / 404 |

| Search | GET | /items?q=term | 200 |

| Bulk action | POST | /items/batch | 200 / 207 |

Documentation Requirements

Every endpoint must document:

• HTTP method and path
• Description
• Request parameters (path, query, body) with types
• Response schema with examples
• Error codes and descriptions
• Authentication requirements

Common Pitfalls

• Using verbs in URLs — Use nouns: /users not /getUsers
• Inconsistent error format — Use the same error schema everywhere
• Missing pagination — Any list endpoint that can grow needs pagination
• No versioning strategy — Decide early: URL (/v1/) or header-based