REST API Design

Design RESTful APIs following industry standards and generate OpenAPI 3.0 specifications.

Quick Reference

Endpoint Pattern

GET    /resources           # List
POST   /resources           # Create
GET    /resources/{id}      # Read
PUT    /resources/{id}      # Replace
PATCH  /resources/{id}      # Update
DELETE /resources/{id}      # Delete

Status Code Selection

Success:  200 OK | 201 Created | 204 No Content
Client:   400 Bad Request | 401 Unauthorized | 403 Forbidden
          404 Not Found | 409 Conflict | 422 Validation Error
Server:   500 Internal Error | 503 Unavailable

URL Naming Rules

• Plural nouns: /users, /products
• Lowercase with hyphens: /user-profiles
• No verbs in paths (HTTP methods are verbs)
• Max 2-3 nesting levels

Workflow

1. Design Endpoints

Define resources and their relationships:

# Core resource
/items                    # Collection
/items/{itemId}           # Instance

# Sub-resources (if tightly coupled)
/items/{itemId}/comments  # Nested collection

See naming-conventions.md for complete patterns.

2. Select HTTP Methods

Choose based on operation semantics:

See http-methods.md for decision tree.

3. Define Status Codes

Match response to outcome:

Creating resource?     → 201 + Location header
Deleting resource?     → 204 (no body)
Validation failed?     → 422 + error details
Auth missing?          → 401
Auth insufficient?     → 403
Not found?             → 404

See status-codes.md for complete decision tree.

4. Add Pagination & Filtering

For collection endpoints:

parameters:
  - name: page
    in: query
    schema: { type: integer, default: 1 }
  - name: limit
    in: query
    schema: { type: integer, default: 20, maximum: 100 }
  - name: sort
    in: query
    schema: { type: string }
    description: "field:direction (e.g., created_at:desc)"

See pagination-filtering-sorting.md for patterns.

5. Choose Versioning Strategy

Recommended: URI path versioning

https://api.example.com/v1/users
https://api.example.com/v2/users

See versioning.md for alternatives.

6. Generate OpenAPI Spec

Use the template at assets/openapi-template.yaml.

Replace placeholders:

• ${API_TITLE} - Your API name
• ${API_DESCRIPTION} - API overview
• ${API_VERSION} - Semantic version

7. Validate Design

Run through validation-checklist.md.

Common Patterns

Error Response

Error:
  type: object
  required: [code, message]
  properties:
    code:
      type: string
      example: VALIDATION_ERROR
    message:
      type: string
      example: Validation failed
    details:
      type: array
      items:
        type: object
        properties:
          field: { type: string }
          message: { type: string }
    requestId:
      type: string

Pagination Response

ListResponse:
  type: object
  properties:
    data:
      type: array
      items: { $ref: '#/components/schemas/Resource' }
    pagination:
      type: object
      properties:
        page: { type: integer }
        limit: { type: integer }
        totalItems: { type: integer }
        totalPages: { type: integer }

Resource with Timestamps

Resource:
  type: object
  required: [id, createdAt, updatedAt]
  properties:
    id:
      type: string
      format: uuid
      readOnly: true
    createdAt:
      type: string
      format: date-time
      readOnly: true
    updatedAt:
      type: string
      format: date-time
      readOnly: true

Resources