api-designlisted

# API Design Comprehensive API design skill combining REST, GraphQL, gRPC, and Python library architecture expertise with patterns, templates, and tools for production-grade APIs. ## When to Activate - Creating new API endpoints (REST, GraphQL, gRPC) - Designing resource hierarchies and schemas - Writing OpenAPI/Swagger specifications - Implementing authentication and authorization - Setting up pagination, filtering, and sorting - Configuring rate limiting and CORS - Designing Python library APIs - Reviewing API designs in pull requests ## Decision Tree: API Style Selection ``` What are you building? +-- CRUD resources with clear entity model? --> REST | Best for: resource-oriented operations, caching, wide tooling support +-- Complex queries with varying client needs? --> GraphQL | Best for: over-fetching prevention, nested data, multiple client types +-- High-throughput service-to-service? --> gRPC | Best for: low latency, strong typing, streaming, polyglot microservices +-- Reusable Python package? --> Python Library API Best for: SDKs, internal tooling, developer experience ``` ## Quick Reference ### RESTful Resource Design **URL Patterns:** - `/api/v1/users` (plural nouns, lowercase with hyphens) - `/api/v1/organizations/{org_id}/teams` (hierarchical, max 2 levels) - Never use verbs: `/getUsers` or underscores: `/user_profiles` **HTTP Methods:** - `GET` - Retrieve (safe, idempotent, cacheable) - `POST` - Create (returns 201 with Location header) - `PUT