youhai020616/pi-extensions/api-design

API Design

Overview

Good APIs are consistent, predictable, and hard to misuse.

Core principle: Design the API from the consumer's perspective first, then implement.

RESTful Design Rules

URL Structure

GET    /api/v1/users          # List
POST   /api/v1/users          # Create
GET    /api/v1/users/:id      # Read
PUT    /api/v1/users/:id      # Replace
PATCH  /api/v1/users/:id      # Partial update
DELETE /api/v1/users/:id      # Delete

Rules:

• Nouns, not verbs (/users not /getUsers)
• Plural resources (/users not /user)
• Nested for relationships (/users/:id/posts)
• Max 2 levels deep — beyond that, use query params or top-level resource
• Lowercase, hyphen-separated (/user-profiles not /userProfiles)

HTTP Methods & Status Codes

Error Response Format

Always use consistent error shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Rules:

• Machine-readable code (UPPER_SNAKE_CASE)
• Human-readable message
• details array for field-level errors
• Never expose stack traces in production

Pagination

GET /api/v1/users?page=2&limit=20
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

For large datasets, prefer cursor-based:

GET /api/v1/events?cursor=abc123&limit=50

Filtering & Sorting

GET /api/v1/users?status=active&role=admin     # Filter
GET /api/v1/users?sort=-created_at,name        # Sort (- = desc)
GET /api/v1/users?fields=id,name,email         # Sparse fields

Versioning

Use URL versioning (/api/v1/) for simplicity:

• Explicit and visible
• Easy to route
• Easy to deprecate

Deprecation flow:

1. Add Sunset header with date
2. Return Warning header
3. Log usage for monitoring
4. Remove after sunset date

Authentication

Security checklist:

• [ ] HTTPS everywhere (no exceptions)
• [ ] Rate limiting per endpoint
• [ ] Input validation on all parameters
• [ ] No sensitive data in URLs (use headers/body)
• [ ] CORS configured correctly
• [ ] Auth tokens expire and refresh

Documentation

Every API endpoint needs:

# Example: OpenAPI / Swagger format
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive]
      responses:
        200:
          description: Success
        401:
          description: Unauthorized

Document:

• All parameters with types and constraints
• All response codes with examples
• Authentication requirements
• Rate limits
• Breaking changes in changelog

Checklist Before Shipping

• [ ] Consistent URL patterns across all endpoints
• [ ] Consistent error format
• [ ] Pagination on all list endpoints
• [ ] Input validation with clear error messages
• [ ] Authentication and authorization
• [ ] Rate limiting
• [ ] CORS headers
• [ ] API documentation / OpenAPI spec
• [ ] Versioning strategy decided
• [ ] No breaking changes without version bump