API Design

API Design

Existing API Patterns

!find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.cs" \) -path "*/route*" -o -path "*/controller*" -o -path "*/handler*" -o -path "*/endpoint*" -o -path "*/api*" 2>/dev/null | grep -v node_modules | grep -v vendor | grep -v .git | head -20

!find . -name "openapi*" -o -name "swagger*" -o -name "*.graphql" -o -name "*.gql" -o -name "schema.*" 2>/dev/null | grep -v node_modules | head -10

Design Process

Step 1: Understand the Domain

1. Identify the resource(s) being modeled
2. Define the data model with all fields and types
3. Map relationships between resources
4. Identify the consumers (frontend, mobile, third-party)

Step 2: Design Endpoints (REST)

For each resource, define:

Step 3: Define Schemas

For each endpoint, define:

• Request body (JSON schema with types, required fields, validation rules)
• Response body (JSON schema with all fields)
• URL parameters (path params, query params for filtering/sorting/pagination)
• Headers (Content-Type, Authorization, custom headers)

Step 4: Error Handling

Standard error response format:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Human-readable description",
    "details": []
  }
}

Standard HTTP status codes:

• 200 OK — successful GET/PUT/PATCH
• 201 Created — successful POST
• 204 No Content — successful DELETE
• 400 Bad Request — validation errors
• 401 Unauthorized — missing/invalid auth
• 403 Forbidden — insufficient permissions
• 404 Not Found — resource doesn't exist
• 409 Conflict — duplicate or state conflict
• 422 Unprocessable Entity — valid JSON but semantic errors
• 429 Too Many Requests — rate limited
• 500 Internal Server Error — unexpected failure

Step 5: Pagination, Filtering, Sorting

Pagination (cursor or offset):

GET /api/v1/users?page=2&per_page=20
GET /api/v1/users?cursor=abc123&limit=20

Filtering:

GET /api/v1/users?status=active&role=admin

Sorting:

GET /api/v1/users?sort=created_at&order=desc

Step 6: Generate Specification

Output an OpenAPI 3.0 spec (YAML) or GraphQL schema as appropriate for the project.

Design Principles

• Use plural nouns for resource names (/users not /user)
• Use kebab-case for multi-word endpoints (/user-profiles)
• Version the API (/api/v1/)
• Be consistent with existing patterns in the project
• Follow REST constraints: stateless, cacheable, uniform interface
• Design for the consumer, not the database schema