---

name: api-design description: RESTful API design principles, patterns, and best practices. Use when building backend APIs. (project) allowed-tools: Read, Grep, Glob, Edit, Write, Bash

API Design Principles

REST Conventions

HTTP Methods

URL Structure

CopyGET    /api/v1/users           # List all users
GET    /api/v1/users/:id       # Get single user
POST   /api/v1/users           # Create user
PUT    /api/v1/users/:id       # Replace user
PATCH  /api/v1/users/:id       # Update user
DELETE /api/v1/users/:id       # Delete user

# Nested resources
GET    /api/v1/users/:id/posts # User's posts

Response Format

Success Response

Copy{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Response

Copy{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

HTTP Status Codes

Success (2xx)

• 200 OK - Successful GET, PUT, PATCH
• 201 Created - Successful POST
• 204 No Content - Successful DELETE

Client Errors (4xx)

• 400 Bad Request - Invalid input
• 401 Unauthorized - Authentication required
• 403 Forbidden - Permission denied
• 404 Not Found - Resource doesn't exist
• 409 Conflict - Resource conflict
• 422 Unprocessable Entity - Validation failed

Server Errors (5xx)

• 500 Internal Server Error - Unexpected error
• 503 Service Unavailable - Temporary unavailable

Pagination

Offset-based

CopyGET /api/v1/users?page=2&limit=20

Cursor-based

CopyGET /api/v1/users?cursor=abc123&limit=20

Filtering & Sorting

CopyGET /api/v1/users?status=active&role=admin
GET /api/v1/users?sort=-created_at,name
GET /api/v1/users?fields=id,name,email

Authentication

JWT Token

CopyAuthorization: Bearer <token>

API Key

CopyX-API-Key: <api-key>

Versioning

URL Path (Recommended)

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

Header

CopyAccept: application/vnd.api+json; version=1

Rate Limiting Headers

CopyX-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000