patterns-api-contracts

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