patterns-api-contracts

Designing API Contracts

Purpose

Design RESTful API contracts that map user actions to endpoints with complete schema definitions and comprehensive error handling. This skill covers endpoint design, request/response schemas, and OpenAPI specification.

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

Anti-Patterns