api-designlisted

This skill should be used when designing or building an API — endpoints, routes, request/response shapes, error formats, pagination, versioning, or deciding REST vs GraphQL. Trigger phrases include "design the API", "build an endpoint", "REST or GraphQL", "how should I structure my routes", "API error format", "paginate results", "version my API", "validate env vars", "idempotency", "what should this endpoint return". It applies proven REST conventions and a clear REST-vs-GraphQL decision, with env-config validation.
MartinOlivero/saas-builder · ★ 1 · API & Backend · score 74

Install: claude install-skill MartinOlivero/saas-builder

# API Design This skill turns "I need an endpoint" into an API that is consistent, predictable, and safe to evolve. It encodes the conventions that the best public APIs (Stripe, Microsoft, GitHub) share. Analogy: an API is the menu of a restaurant. A good menu is consistent — every dish described the same way, prices where you expect, no surprises. A messy menu makes every order a negotiation. ## Discovery (max 3 questions, only if unknown) 1. Who consumes this — your own React SPA only, or also mobile / partners / the public? 2. Is it mostly simple CRUD, or deeply nested reads across many relations? 3. Is it public-facing (needs versioning + stability) or internal? ## Step 1 — REST vs GraphQL (decide first) **Default to REST.** Reach for **GraphQL only when**: clients need flexible, deeply nested reads across many relations; you have multiple divergent clients (web + mobile + partners); or you're composing several backend services. For a single React SPA on one Postgres DB, REST (or tRPC for end-to-end TS types) is simpler and cacheable. If you do choose GraphQL: - **Solve N+1 from day one with DataLoader** (batch + cache per request). - Design the schema around the domain graph, not DB tables. - Paginate every list field (Relay-style `edges/node/pageInfo`); enforce depth/complexity limits. - Mutations return the mutated object so clients update cache without a refetch. ## Step 2 — REST conventions (the defaults) - **Resources are plural nouns**: `/invoices`, `/invo