name: patterns-api-contracts description: This skill should be used when the user asks to "design API", "map endpoints", "define schemas", or mentions "API", "endpoint", "REST", "OpenAPI", "schema", "contract", or "HTTP". Provides RESTful API design with endpoint mapping, request/response schemas, and comprehensive error handling.

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