API Designer

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)

Client Errors (4xx)

Server Errors (5xx)

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