Phase 4: API Design

Design your API contracts before implementation.

Purpose

Phase 4 defines the communication layer between frontend and backend. Well-designed APIs reduce integration friction and enable parallel development.

Actions

Action	Description	Example
start	Begin Phase 4	$phase-4-api start
endpoints	List all endpoints	$phase-4-api endpoints
test	Generate API test plan	$phase-4-api test

Deliverables

1. API Endpoint List - All routes with methods
2. Request/Response Schemas - Per-endpoint data contracts
3. Authentication Spec - Auth flow and token handling
4. Error Response Format - Standardized error structure
5. API Document - docs/02-design/api.md

Process

Step 1: Resource Identification

Map entities from Phase 1 to API resources:

| Entity | Resource Path | Methods |
|--------|--------------|---------|
| User | /api/users | GET, POST |
| User (single) | /api/users/:id | GET, PUT, DELETE |
| Post | /api/posts | GET, POST |
| Post (single) | /api/posts/:id | GET, PUT, DELETE |
| Comment | /api/posts/:id/comments | GET, POST |

Step 2: Endpoint Specifications

For each endpoint:

### POST /api/users
- **Description**: Create new user
- **Auth**: None (public)
- **Request Body**:
  ```json
  { "email": "string", "name": "string", "password": "string" }

• Response 201:

  { "id": "uuid", "email": "string", "name": "string", "created_at": "datetime" }
  

• Errors: 400 (validation), 409 (email exists)

### Step 3: Authentication Design

```markdown
## Auth Flow
1. POST /api/auth/login -> Returns { access_token, refresh_token }
2. Include `Authorization: Bearer <token>` in subsequent requests
3. POST /api/auth/refresh -> Renew expired access token
4. POST /api/auth/logout -> Invalidate tokens

## Token Specs
- Access token: JWT, 15min expiry
- Refresh token: opaque, 7d expiry, stored in httpOnly cookie

Step 4: Error Response Standard

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ]
  }
}

Step 5: API Testing with Zero Script QA

Use Docker logs and curl for testing without test scripts:

# Test user creation
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","name":"Test","password":"pass123"}'

# Check docker logs for errors
docker logs app-container --tail 50

API Patterns

See references/api-patterns.md for REST conventions, pagination, filtering, and versioning patterns.

Output Location

docs/02-design/
├── api.md             # Full API specification
├── auth-flow.md       # Authentication design
└── error-codes.md     # Error code reference

Next Phase

When API design is complete, proceed to $phase-5-design-system for component library.

Common Mistakes

Mistake	Solution
Inconsistent naming	Use plural nouns for resources
No pagination	Always paginate list endpoints
Missing error codes	Define all error responses upfront
No versioning plan	Use URL prefix /api/v1/ from start
Tight coupling	Design for frontend/backend independence