# Peopleforrester Claude Dotfiles API Designer > API Designer - Skill: `tomevault-io/peopleforrester-claude-dotfiles-api-designer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/peopleforrester-claude-dotfiles-api-designer` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/peopleforrester-claude-dotfiles-api-designer/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/peopleforrester-claude-dotfiles-api-designer --- # API Designer Design consistent, intuitive, and well-documented APIs. ## When to Use - Designing new API endpoints - Reviewing existing API structure - Creating API documentation - Planning API versioning strategy - Designing error responses ## REST API Design Principles ### URL Structure ``` GET /resources # List resources GET /resources/:id # Get single resource POST /resources # Create resource PUT /resources/:id # Replace resource PATCH /resources/:id # Update resource partially DELETE /resources/:id # Delete resource ``` ### Naming Conventions - Use **nouns** for resources: `/users`, `/orders`, `/products` - Use **plural** form: `/users` not `/user` - Use **kebab-case** for multi-word: `/order-items` - Use **path params** for identification: `/users/:id` - Use **query params** for filtering: `/users?status=active` ### Nested Resources ``` GET /users/:userId/orders # User's orders GET /users/:userId/orders/:orderId # Specific order POST /users/:userId/orders # Create order for user ``` Keep nesting shallow (max 2 levels). ## Request/Response Design ### Request Body ```json { "name": "John Doe", "email": "john@example.com", "preferences": { "newsletter": true, "theme": "dark" } } ``` - Use camelCase for property names - Required fields should be documented - Include validation constraints ### Success Response ```json { "data": { "id": "123", "name": "John Doe", "email": "john@example.com", "createdAt": "2026-01-15T10:30:00Z" } } ``` ### List Response with Pagination ```json { "data": [ { "id": "1", "name": "Item 1" }, { "id": "2", "name": "Item 2" } ], "meta": { "page": 1, "perPage": 20, "total": 100, "totalPages": 5 }, "links": { "self": "/items?page=1", "next": "/items?page=2", "last": "/items?page=5" } } ``` ### Error Response (RFC 7807) ```json { "type": "https://api.example.com/errors/validation", "title": "Validation Error", "status": 400, "detail": "The request body contains invalid data", "instance": "/users/123", "errors": [ { "field": "email", "message": "Invalid email format" } ] } ``` ## HTTP Status Codes ### Success (2xx) | Code | Use When | |------|----------| | 200 OK | Request succeeded (GET, PUT, PATCH) | | 201 Created | Resource created (POST) | | 204 No Content | Success with no body (DELETE) | ### Client Errors (4xx) | Code | Use When | |------|----------| | 400 Bad Request | Malformed request / validation error | | 401 Unauthorized | Missing or invalid authentication | | 403 Forbidden | Authenticated but not authorized | | 404 Not Found | Resource doesn't exist | | 409 Conflict | Resource conflict (duplicate) | | 422 Unprocessable | Valid syntax but semantic error | | 429 Too Many Requests | Rate limit exceeded | ### Server Errors (5xx) | Code | Use When | |------|----------| | 500 Internal Error | Unexpected server error | | 502 Bad Gateway | Upstream service error | | 503 Unavailable | Service temporarily unavailable | ## API Versioning ### URL Path (Recommended) ``` /v1/users /v2/users ``` ### Header-based ``` Accept: application/vnd.api+json; version=1 ``` ## Authentication ### Bearer Token ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` ### API Key ``` X-API-Key: sk_live_abc123... ``` ## Documentation Template ```markdown ## Create User Creates a new user account. ### Request `POST /v1/users` #### Headers | Header | Required | Description | |--------|----------|-------------| | Authorization | Yes | Bearer token | | Content-Type | Yes | application/json | #### Body | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | User's full name | | email | string | Yes | Email address (unique) | #### Example \`\`\`json { "name": "John Doe", "email": "john@example.com" } \`\`\` ### Response #### 201 Created \`\`\`json { "data": { "id": "usr_123", "name": "John Doe", "email": "john@example.com", "createdAt": "2026-01-15T10:30:00Z" } } \`\`\` #### 400 Bad Request \`\`\`json { "type": "validation_error", "title": "Validation Error", "status": 400, "errors": [ { "field": "email", "message": "Email already exists" } ] } \`\`\` ``` ## Design Checklist - [ ] Resource names are nouns, plural - [ ] HTTP methods used correctly - [ ] Consistent response format - [ ] Proper status codes - [ ] Pagination for lists - [ ] Versioning strategy defined - [ ] Authentication documented - [ ] Error format standardized - [ ] Rate limiting documented --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/peopleforrester) — claim your Tome and manage your conversions.