api-patterns

# API Patterns Skill ## REST API Design ### Resource Naming ``` # Collection GET /api/v1/documents # List documents POST /api/v1/documents # Create document # Single resource GET /api/v1/documents/{id} # Get document PUT /api/v1/documents/{id} # Replace document PATCH /api/v1/documents/{id} # Update document DELETE /api/v1/documents/{id} # Delete document # Nested resources GET /api/v1/users/{id}/documents # User's documents ``` ### HTTP Status Codes | Code | Meaning | When to Use | |------|---------|-------------| | 200 | OK | Successful GET/PUT/PATCH | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Malformed request or an established domain refusal | | 401 | Unauthorized | Missing/invalid auth | | 403 | Forbidden | No permission | | 404 | Not Found | Resource doesn't exist | | 405 | Method Not Allowed | Unsupported method; preserve Allow | | 409 | Conflict | Duplicate resource or current-state conflict | | 412 | Precondition Failed | Supplied concurrency version is stale | | 422 | Unprocessable | Validation error | | 428 | Precondition Required | Required concurrency precondition is missing | | 429 | Too Many Requests | Rate limited | | 500 | Internal Error | Server error | | 503 | Service Unavailable | Dependency temporarily unavailable | ### Response Format Follow the host's existing resource and collection contract. This envelope is illustrative; do not impose it on a frame...