api-designlisted

Generates RESTful and GraphQL API designs with OpenAPI specs, proper resource naming, HTTP method usage, status codes, pagination, filtering, error responses, versioning strategies, and GraphQL schema patterns. Triggers on: "design API", "create API spec", "OpenAPI", "REST endpoint design", "GraphQL schema".
timwukp/agent-skills-best-practice · ★ 3 · API & Backend · score 79

Install: claude install-skill timwukp/agent-skills-best-practice

# API Design ## Instructions ### Step 1: Gather Requirements Ask: 1. What resources does this API manage? (e.g., users, orders, products) 2. What operations are needed? (CRUD, search, bulk operations, async jobs) 3. Who consumes it? (internal services, public clients, mobile apps) 4. Auth model? (API key, OAuth2, JWT) 5. Output format preference? (OpenAPI 3.0 YAML, endpoint list, or both) ### Step 2: Resource Naming Apply these naming conventions: | Rule | Good | Bad | |------|------|-----| | Plural nouns | `/users` | `/user`, `/getUsers` | | Nested resources | `/users/{id}/orders` | `/getUserOrders` | | Lowercase with hyphens | `/order-items` | `/orderItems`, `/order_items` | | No verbs in URLs | `/users/{id}/activate` (POST) | `/activateUser` | | Max 3 levels deep | `/users/{id}/orders` | `/users/{id}/orders/{id}/items/{id}/reviews` | For deeply nested resources, promote to top-level with query filters: ``` GET /reviews?order_id=123&user_id=456 ``` ### Step 3: HTTP Methods and Status Codes Map operations to methods: | Operation | Method | Success Code | Response Body | |-----------|--------|-------------|---------------| | List/Search | GET | 200 | Collection | | Get single | GET | 200 | Resource | | Create | POST | 201 | Created resource + Location header | | Full update | PUT | 200 | Updated resource | | Partial update | PATCH | 200 | Updated resource | | Delete | DELETE | 204 | Empty | | Async operation | POST | 202 | Job status + Location header | **Error cod