API First Design

Overview

Design the API contract first, then build frontend and backend in parallel. Small teams move faster when everyone agrees on the interface upfront.

---

1. When to Apply

| Trigger | Behavior | |---------|----------| | Starting new API | Full API design workflow | | "OpenAPI", "API design" | Schema generation | | Frontend/backend need to work in parallel | Contract-first setup |

---

2. Design Workflow

Step 1: Define Resources

From domain description, identify:

• Nouns → Resources (User, Post, Order)
• Verbs → Operations (create, list, update, delete)
• Relationships → Nested routes or query params

Step 2: Generate OpenAPI Spec

openapi: 3.1.0
info:
  title: My App API
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/User' }
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateUser' }
      responses:
        '201':
          description: Created
components:
  schemas:
    User:
      type: object
      properties:
        id: { type: string, format: uuid }
        email: { type: string, format: email }
        name: { type: string }
        createdAt: { type: string, format: date-time }
    CreateUser:
      type: object
      required: [email, name]
      properties:
        email: { type: string, format: email }
        name: { type: string, minLength: 1, maxLength: 100 }

Step 3: API Design Rules

• Use plural nouns: /users not /user
• Version your API: /api/v1/
• Consistent error format: { error: { code, message, details } }
• Pagination: cursor-based for large sets, offset for small
• Filtering: ?status=active&sort=-createdAt

---

3. REST vs GraphQL Decision

| Factor | REST | GraphQL | |--------|------|---------| | Multiple clients with different needs | ❌ Over/under-fetching | ✅ Client-driven queries | | Simple CRUD | ✅ Standard patterns | ❌ Overkill | | Caching | ✅ HTTP caching built-in | ⚠️ Requires effort | | Team size < 5 | ✅ Simpler to learn | ❌ Learning curve | | Startup default | ✅ Start here | Consider at scale |

---

4. Tool Coordination

| Tool | Purpose | |------|---------| | Write | Generate OpenAPI/GraphQL schemas | | Read | Analyze existing API code | | Bash | Generate stubs (npx openapi-generator-cli generate) |

---

5. Boundaries

Will:

• Design RESTful APIs with OpenAPI specs
• Design GraphQL schemas
• Generate server stubs and client types
• Apply API design best practices

Will Not:

• Implement business logic behind endpoints
• Set up API gateways or rate limiting infrastructure
• Handle authentication design (use security-audit)
• Load test APIs