api-design-standards_skill

Overview

This skill designs RESTful APIs following Grey Haven standards for FastAPI and TanStack Start server functions. It produces consistent routes, Pydantic schemas, status codes, pagination, error responses, and OpenAPI-friendly documentation. Use it to enforce multi-tenant isolation, validation, and production-safe defaults like CORS and rate limiting.

How this skill works

I generate FastAPI route patterns, Pydantic request/response models, repository-aware service stubs, and standard error handlers. I enforce tenant isolation by extracting tenant_id from JWT, wire status codes and response models, and provide pagination (offset and cursor) and rate-limit integration. I also produce clear docstrings and OpenAPI parameter/response hints so docs are autogenerated and accurate.

When to use it

• Creating new FastAPI endpoints or TanStack Start server functions
• Designing RESTful resource hierarchies and URL patterns
• Writing Pydantic schemas for request validation and responses
• Implementing pagination, filtering, sorting, or cursor semantics
• Configuring error handling, OpenAPI docs, CORS, or rate limiting
• Reviewing API design in pull requests or writing endpoint tests

Best practices

• Use plural, hyphenated, versioned routes (e.g., /api/v1/users) and avoid verbs in URLs
• Always extract tenant_id from JWT and construct tenant-aware repositories to prevent data leaks
• Define Create/Read/Update schemas and never return sensitive fields (password hashes, secrets)
• Return correct HTTP status codes: 201 for create, 204 for delete, 422 for validation errors, 404 for missing resources
• Prefer cursor-based pagination for large datasets; use offset for simple lists and include total where appropriate
• Add docstrings, summary/description, and response models so FastAPI generates accurate OpenAPI docs

Example use cases

• Scaffold a users CRUD router with tenant-aware repository, Pydantic models, and tests
• Add cursor pagination to a large listing endpoint and return next_cursor for client continuation
• Create standardized error handlers that return {error, detail, status_code} for API clients
• Protect public listing endpoints with Upstash Redis rate limiter and configure CORS via environment (Doppler)
• Implement a TanStack Start server function that validates input with zod and enforces tenant isolation