Designing API Contracts

Overview

Design RESTful API contracts that map user actions to endpoints with complete schema definitions and comprehensive error handling. Every user action becomes an endpoint; every endpoint has request/response schemas and error handling.

When to Use

• Designing new API endpoints for a feature
• Mapping user actions to HTTP methods and paths
• Creating OpenAPI specifications from requirements
• Defining request/response schemas for endpoints
• Documenting error responses for an API
• Integrating with existing API patterns (brownfield)
• Creating contracts/ directory artifacts

When NOT to Use

• GraphQL API design - Different paradigm, not RESTful
• WebSocket or real-time streaming - Use specialized patterns
• Internal microservice communication - When external contracts aren't needed
• Entity modeling - Use humaninloop:patterns-entity-modeling first
• Technical architecture decisions - Use humaninloop:patterns-technical-decisions

Endpoint Mapping

User Action to Endpoint Mapping

| User Action | HTTP Method | Endpoint Pattern | |-------------|-------------|------------------| | Create resource | POST | /resources | | List resources | GET | /resources | | Get single resource | GET | /resources/{id} | | Update resource | PUT/PATCH | /resources/{id} | | Delete resource | DELETE | /resources/{id} | | Perform action | POST | /resources/{id}/{action} | | Get nested resource | GET | /resources/{id}/children |

Method Selection

| Scenario | Method | Idempotent? | |----------|--------|-------------| | Create new resource | POST | No | | Full replacement | PUT | Yes | | Partial update | PATCH | No | | Read resource | GET | Yes | | Remove resource | DELETE | Yes | | Trigger action | POST | Usually No |

Resource Naming Conventions

• Use plural nouns: /users, not /user
• Use kebab-case for multi-word: /user-profiles
• Use path params for IDs: /users/{userId}
• Use query params for filtering: /users?role=admin
• Use nested paths for relationships: /users/{userId}/tasks

Endpoint Documentation Format

Document each endpoint with description, source requirements, request/response schemas, and error cases:

## POST /api/auth/login

**Description**: Authenticate user with email and password

**Source Requirements**: FR-001, US#1

### Request
{JSON request body example}

### Response (200 OK)
{JSON response body example}

### Error Responses
| Status | Code | Description |
|--------|------|-------------|
| 400 | INVALID_INPUT | Missing or malformed fields |
| 401 | INVALID_CREDENTIALS | Wrong email or password |

Schema Definition

Request Schema Format

LoginRequest:
  type: object
  required:
    - email
    - password
  properties:
    email:
      type: string
      format: email
      description: User's email address
    password:
      type: string
      minLength: 8
      description: User's password

Type Mapping from Data Model

| Data Model Type | OpenAPI Type | Format | |-----------------|--------------|--------| | UUID | string | uuid | | Text | string | - | | Email | string | email | | URL | string | uri | | Integer | integer | int32/int64 | | Decimal | number | float/double | | Boolean | boolean | - | | Timestamp | string | date-time | | Date | string | date | | Enum[a,b,c] | string | enum: [a,b,c] |

Error Response Design

Use standard error format with machine-readable codes and human-readable messages.

See ERROR-PATTERNS.md for complete HTTP status codes, error code conventions, and response formats.

Quick Reference

| Status | When to Use | |--------|-------------| | 400 | Invalid input format | | 401 | Missing/invalid auth | | 403 | No permission | | 404 | Resource missing | | 409 | State conflict | | 422 | Business rule violation | | 429 | Rate limit exceeded | | 500 | Server error |

List Endpoints

For endpoints returning collections, implement pagination, filtering, and sorting.

See PAGINATION-PATTERNS.md for offset vs cursor pagination, filtering operators, and sorting patterns.

Quick Reference

GET /api/users?page=1&limit=20&role=admin&sort=-createdAt

Brownfield Considerations

When existing API patterns are detected, align new endpoints:

| Aspect | Check For | |--------|-----------| | Base path | /api/v1, /api, etc. | | Auth pattern | Bearer, API key, session | | Error format | Existing error structure | | Pagination | page/limit, cursor, offset |

Handle endpoint collisions:

• REUSE existing endpoints when possible
• RENAME to match existing patterns
• NEW only when no existing endpoint fits

OpenAPI Structure

See OPENAPI-TEMPLATE.yaml for a complete, copy-ready template with all sections.

Minimal Structure

openapi: 3.0.3
info:
  title: {Feature Name} API
  version: 1.0.0

servers:
  - url: /api

paths:
  /resource:
    get: ...
    post: ...

components:
  schemas: ...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

security:
  - bearerAuth: []

Traceability

Track endpoint to requirement mapping:

| Endpoint | Method | FR | US | Description | |----------|--------|-----|-----|-------------| | /auth/login | POST | FR-001 | US#1 | User login | | /users/me | GET | FR-004 | US#4 | Get current user |

Validation

Validate OpenAPI specifications using the validation script:

python scripts/validate-openapi.py path/to/openapi.yaml

Checks: OpenAPI syntax, REST conventions, error responses, request bodies, operation IDs, security schemes, examples, and descriptions.

Quality Checklist

Before finalizing API contracts:

• [ ] Every user action has an endpoint
• [ ] All endpoints have request schema (if applicable)
• [ ] All endpoints have success response schema
• [ ] All endpoints have error responses defined
• [ ] Naming follows REST conventions
• [ ] Authentication requirements documented
• [ ] Brownfield patterns matched (if applicable)
• [ ] OpenAPI spec is valid
• [ ] Traceability to requirements complete

Common Mistakes

Verbs in URLs

❌ /getUsers, /createUser, /deleteUser ✅ /users with appropriate HTTP methods (GET, POST, DELETE)

GET for State-Changing Actions

❌ GET /users/{id}/delete ✅ DELETE /users/{id} or POST /users/{id}/archive

Missing Error Responses

❌ Only documenting 200 OK response ✅ Define all error cases: 400, 401, 403, 404, 409, 422, 500

Inconsistent Naming

❌ Mixing /user-profiles, /userSettings, /user_preferences ✅ Pick one style consistently: /user-profiles, /user-settings, /user-preferences

Generic Error Codes

❌ Just returning 400 or 500 for all errors ✅ Specific codes: INVALID_EMAIL, USER_NOT_FOUND, RATE_LIMIT_EXCEEDED

Missing Examples

❌ Schema definitions without realistic example values ✅ Include example: fields showing real-world data

Skipping Brownfield Check

❌ Creating new patterns when existing API conventions exist ✅ Always check existing API style (auth, error format, pagination) first