dev-api-design

# API Design Use this skill for contract-first API design across REST, GraphQL, gRPC, tRPC, AsyncAPI, and agent-facing interfaces. It owns contract choice, auth boundaries, versioning, errors, pagination, rate limits, idempotency, and validation; it does not replace backend implementation or security review. ## Style Decision Table | API style | Choose when | Avoid when | Canonical artifact | |-----------|-------------|------------|--------------------| | REST + OpenAPI | Public APIs, broad tooling compatibility, cacheable resources | Sub-10ms internal calls, streaming-first | OpenAPI 3.2.0 | | GraphQL | Complex client-driven query shapes, multi-team schema ownership | Simple CRUD, caching is critical, single-team | GraphQL SDL | | gRPC | Internal services, bidirectional streaming, type-critical boundaries | Public internet consumers, browser-native clients | protobuf | | tRPC | TypeScript monorepos with shared server+client | Non-TS stacks, public third-party consumers | TypeScript types | | AsyncAPI + webhooks | Event-driven contracts, pub/sub, push notifications | Synchronous request-reply | AsyncAPI 3.x | | MCP tool layer | Agent or LLM is the primary consumer | Human-only clients | MCP tool schema | ## Quick Reference | API style | Load | |-----------|------| | REST + OpenAPI | [references/restful-design-patterns.md](references/restful-design-patterns.md), [references/openapi-guide.md](references/openapi-guide.md) | | GraphQL | [references/graphql-patterns.md](refer...