patterns-api-contracts

What this skill does

# 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:

```markdown
## 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

```yaml
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](references/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](references/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](references/OPENAPI-TEMPLATE.yaml) for a complete, copy-ready template with all sections.

### Minimal Structure

```yaml
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:

```bash
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