api-design

API Design

When to use this skill

• Designing new API endpoints
• Adding routes to an existing API
• Improving API error handling or validation
• Documenting APIs (OpenAPI/Swagger)
• Reviewing API design for best practices

RESTful conventions

URL structure

GET    /users          → List users
POST   /users          → Create user
GET    /users/:id      → Get single user
PUT    /users/:id      → Replace user
PATCH  /users/:id      → Partial update
DELETE /users/:id      → Delete user

GET    /users/:id/orders    → List user's orders (nested resource)
POST   /users/:id/orders    → Create order for user

Naming rules

• Plural nouns for resources: /users not /user
• Kebab-case for multi-word: /order-items not /orderItems
• No verbs in URLs: POST /users not POST /createUser
• Nest logically: Max 2 levels deep, then use query params

HTTP status codes

Code	When to use
200	Success (GET, PUT, PATCH)
201	Created (POST)
204	No content (DELETE)
400	Bad request (validation error)
401	Unauthorized (no/invalid auth)
403	Forbidden (insufficient permissions)
404	Not found
409	Conflict (duplicate, state conflict)
422	Unprocessable entity (semantic error)
429	Too many requests (rate limit)
500	Internal server error

Request/Response patterns

Consistent response envelope

// Success
{
  "data": { "id": 1, "name": "Alice" },
  "meta": { "requestId": "abc-123" }
}

// List with pagination
{
  "data": [{ "id": 1 }, { "id": 2 }],
  "meta": {
    "total": 45,
    "page": 1,
    "perPage": 20,
    "totalPages": 3
  }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "Must be a valid email" }
    ]
  }
}

Pagination

GET /users?page=2&per_page=20        # Offset-based
GET /users?cursor=eyJpZCI6MTB9&limit=20  # Cursor-based (preferred for large datasets)