name: api-design description: This skill should be used for REST API, GraphQL, versioning, pagination, authentication, backend routes, web services, HTTP endpoints, server API design whenToUse: API design, endpoints, REST patterns, backend development, web services, HTTP routes, server-side endpoints, Express routes, FastAPI endpoints whenNotToUse: Internal interfaces, non-HTTP APIs, frontend-only code seeAlso:

• skill: security-checklist when: securing API endpoints
• skill: architecture-patterns when: designing API layer architecture
• skill: database-patterns when: API data modeling

API Design

REST API design best practices.

URL Structure

GET    /users          # List
GET    /users/:id      # Get one
POST   /users          # Create
PUT    /users/:id      # Replace
PATCH  /users/:id      # Update
DELETE /users/:id      # Delete

Versioning

/api/v1/users          # URL versioning
Accept: application/vnd.api.v1+json  # Header

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [{"field": "email", "issue": "invalid format"}]
  }
}

Status Codes