dev-api-design
Installation
SKILL.md
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 |