grey-haven-api-design

# Grey Haven API Design Standards

**RESTful API design for FastAPI backends and TanStack Start server functions.**

Follow these standards when creating API endpoints, defining schemas, and handling errors in Grey Haven projects.

## Supporting Documentation

- **[examples/](examples/)** - Complete endpoint examples (all files <500 lines)
  - [fastapi-crud.md](examples/fastapi-crud.md) - CRUD endpoints with repository pattern
  - [pydantic-schemas.md](examples/pydantic-schemas.md) - Request/response schemas
  - [tanstack-start.md](examples/tanstack-start.md) - Server functions
  - [pagination.md](examples/pagination.md) - Pagination patterns
  - [testing.md](examples/testing.md) - API testing
- **[reference/](reference/)** - Configuration references (all files <500 lines)
  - [fastapi-setup.md](reference/fastapi-setup.md) - Main app configuration
  - [openapi.md](reference/openapi.md) - OpenAPI customization
  - [error-handlers.md](reference/error-handlers.md) - Exception handlers
  - [authentication.md](reference/authentication.md) - JWT configuration
  - [cors-rate-limiting.md](reference/cors-rate-limiting.md) - CORS and rate limiting
- **[templates/](templates/)** - Copy-paste ready endpoint templates
- **[checklists/](checklists/)** - API design and security checklists

## Quick Reference

### RESTful Resource Design

**URL Patterns:**
- ✅ `/api/v1/users` (plural nouns, lowercase with hyphens)
- ✅ `/api/v1/organizations/{org_id}/teams` (hierarchical)
- ❌ `/api/v1/getUsers` (no verbs in URLs)
- ❌ `/api/v1/user_profiles` (no underscores)

**HTTP Verbs:**
- `GET` - Retrieve resources
- `POST` - Create new resources
- `PUT` - Update entire resource
- `PATCH` - Update partial resource
- `DELETE` - Remove resource

### HTTP Status Codes

**Success:**
- `200 OK` - GET, PUT, PATCH requests
- `201 Created` - POST request (resource created)
- `204 No Content` - DELETE request

**Client Errors:**
- `400 Bad Request` - Invalid request data
- `401 Unauthorized` - Missing/in