API Designer

Design consistent, intuitive, and well-documented APIs.

When to Use

• Designing new API endpoints
• Reviewing existing API structure
• Creating API documentation
• Planning API versioning strategy
• Designing error responses

REST API Design Principles

URL Structure

GET    /resources           # List resources
GET    /resources/:id       # Get single resource
POST   /resources           # Create resource
PUT    /resources/:id       # Replace resource
PATCH  /resources/:id       # Update resource partially
DELETE /resources/:id       # Delete resource

Naming Conventions

• Use nouns for resources: /users, /orders, /products
• Use plural form: /users not /user
• Use kebab-case for multi-word: /order-items
• Use path params for identification: /users/:id
• Use query params for filtering: /users?status=active

Nested Resources

GET /users/:userId/orders           # User's orders
GET /users/:userId/orders/:orderId  # Specific order
POST /users/:userId/orders          # Create order for user

Keep nesting shallow (max 2 levels).

Request/Response Design

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "preferences": {
    "newsletter": true,
    "theme": "dark"
  }
}

• Use camelCase for property names
• Required fields should be documented
• Include validation constraints

Success Response

{
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com",
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

List Response with Pagination

{
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5
  },
  "links": {
    "self": "/items?page=1",
    "next": "/items?page=2",
    "last": "/items?page=5"
  }
}

Error Response (RFC 7807)

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid data",
  "instance": "/users/123",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

HTTP Status Codes

Success (2xx)

Code	Use When
200 OK	Request succeeded (GET, PUT, PATCH)
201 Created	Resource created (POST)
204 No Content	Success with no body (DELETE)

Client Errors (4xx)

Code	Use When
400 Bad Request	Malformed request / validation error
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Authenticated but not authorized
404 Not Found	Resource doesn't exist
409 Conflict	Resource conflict (duplicate)
422 Unprocessable	Valid syntax but semantic error
429 Too Many Requests	Rate limit exceeded

Server Errors (5xx)

Code	Use When
500 Internal Error	Unexpected server error
502 Bad Gateway	Upstream service error
503 Unavailable	Service temporarily unavailable

API Versioning

URL Path (Recommended)

/v1/users
/v2/users

Header-based

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

Authentication

Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key

X-API-Key: sk_live_abc123...

Documentation Template

## Create User

Creates a new user account.

### Request

`POST /v1/users`

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

#### Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | User's full name |
| email | string | Yes | Email address (unique) |

#### Example

\`\`\`json
{
  "name": "John Doe",
  "email": "john@example.com"
}
\`\`\`

### Response

#### 201 Created

\`\`\`json
{
  "data": {
    "id": "usr_123",
    "name": "John Doe",
    "email": "john@example.com",
    "createdAt": "2026-01-15T10:30:00Z"
  }
}
\`\`\`

#### 400 Bad Request

\`\`\`json
{
  "type": "validation_error",
  "title": "Validation Error",
  "status": 400,
  "errors": [
    { "field": "email", "message": "Email already exists" }
  ]
}
\`\`\`

Design Checklist

• Resource names are nouns, plural
• HTTP methods used correctly
• Consistent response format
• Proper status codes
• Pagination for lists
• Versioning strategy defined
• Authentication documented
• Error format standardized
• Rate limiting documented