Skip to content

Tibsfox/gsd-skill-creator / examples/skills/patterns/api-design

api-design

Verified

REST API design best practices. Use when designing APIs, choosing status codes, or creating endpoints.

REST API Design

Endpoint Rules

  • Nouns, not verbs: /users not /getUsers — HTTP method is the verb
  • Plural nouns: /users, /orders — consistent collections
  • Kebab-case: /user-profiles not /user_profiles
  • Max 2 levels nesting: /users/{id}/orders — deeper use query params
  • No trailing slashes, no extensions

HTTP Methods

MethodPurposeIdempotent
GETRetrieveYes
POSTCreateNo
PUTReplace entire resourceYes
PATCHPartial updateNo
DELETERemoveYes

Status Codes

CodeUse When
200Success with body
201Resource created (+ Location header)
204Success, no body (DELETE)
400Malformed request
401Not authenticated
403Authenticated but forbidden
404Not found
409Conflict (duplicate)
422Valid syntax, invalid semantics
429Rate limited

Error Format

{"error": {"code": "VALIDATION_ERROR", "message": "...", "details": [], "request_id": "req_..."}}

Key Rules

  • Always paginate lists (cursor-based preferred, max page size enforced)
  • Never expose sequential IDs — use UUIDs
  • Auth credentials in headers, never URLs
  • Return 400 for unknown parameters (catch typos)
  • Include request_id in every response
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall