Design RESTful APIs following Grey Haven standards - FastAPI routes, Pydantic schemas, HTTP status codes, pagination, filtering, error responses, OpenAPI docs, and multi-tenant patterns. Use when creating API endpoints, designing REST resources, implementing server functions, configuring FastAPI, writing Pydantic schemas, setting up error handling, implementing pagination, or when user mentions 'API', 'endpoint', 'REST', 'FastAPI', 'Pydantic', 'server function', 'OpenAPI', 'pagination', 'validation', 'error handling', 'rate limiting', 'CORS', or 'authentication'.
View on GitHubgreyhaven-ai/claude-code-config
developer-experience
grey-haven-plugins/developer-experience/skills/api-design-standards/SKILL.md
January 21, 2026
Select agents to install to:
npx add-skill https://github.com/greyhaven-ai/claude-code-config/blob/main/grey-haven-plugins/developer-experience/skills/api-design-standards/SKILL.md -a claude-code --skill grey-haven-api-designInstallation paths:
.claude/skills/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/inIssues Found: