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

Method Selection

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

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

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:

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:

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