version: "1.0.0" name: api-design description: "Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API." source: "Internal engineering practices, REST API conventions" domain: "architecture" level: "intermediate" agents: ["backend-dev", "gis"] created_date: "2026-04-27" last_validated: "" validated_by: "" status: "draft"

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

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

Documentation Requirements

Every endpoint must document:

1. HTTP method and path
2. Description
3. Request parameters (path, query, body) with types
4. Response schema with examples
5. Error codes and descriptions
6. 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