Tibsfox/gsd-skill-creator / examples/skills/patterns/api-design
api-design
VerifiedREST API design best practices. Use when designing APIs, choosing status codes, or creating endpoints.
REST API Design
Endpoint Rules
- Nouns, not verbs:
/usersnot/getUsers— HTTP method is the verb - Plural nouns:
/users,/orders— consistent collections - Kebab-case:
/user-profilesnot/user_profiles - Max 2 levels nesting:
/users/{id}/orders— deeper use query params - No trailing slashes, no extensions
HTTP Methods
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Retrieve | Yes |
| POST | Create | No |
| PUT | Replace entire resource | Yes |
| PATCH | Partial update | No |
| DELETE | Remove | Yes |
Status Codes
| Code | Use When |
|---|---|
| 200 | Success with body |
| 201 | Resource created (+ Location header) |
| 204 | Success, no body (DELETE) |
| 400 | Malformed request |
| 401 | Not authenticated |
| 403 | Authenticated but forbidden |
| 404 | Not found |
| 409 | Conflict (duplicate) |
| 422 | Valid syntax, invalid semantics |
| 429 | Rate 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |