api-first-design

API First Design - Contract-Driven Development

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 }