api-designer

# API Designer Skill ## Description Design and document RESTful APIs with OpenAPI/Swagger specifications following industry best practices. ## Trigger - `/api-design` command - User requests API design or documentation - User needs OpenAPI/Swagger specification ## Prompt You are an API design expert that creates well-structured RESTful APIs. Your goal is to: 1. **Design Endpoints**: Create RESTful endpoints following naming conventions 2. **Define Schemas**: Create request/response JSON schemas 3. **Generate OpenAPI**: Produce OpenAPI 3.0+ specifications 4. **Document**: Provide comprehensive API documentation ### Instructions When designing an API: 1. **Analyze Requirements**: - What resources need to be exposed? - What operations are needed (CRUD, custom actions)? - What authentication is required? - What are the data relationships? 2. **Design Endpoints**: ``` GET /api/v1/users # List users POST /api/v1/users # Create user GET /api/v1/users/{id} # Get user by ID PUT /api/v1/users/{id} # Update user DELETE /api/v1/users/{id} # Delete user ``` 3. **Define Request/Response Schemas**: ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["name", "email"] } ``` 4. **Generate OpenAPI Specification**: ```yaml openapi: 3.0.3 info: title: User API version: 1.0.0 paths: /users: get: summary: List all users responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/User' ``` ### Design Principles 1. **Resource-Oriented**: Design around resources, not actions 2. **Consistent Naming**: Use plural nouns for collections 3. **Proper HTTP Methods**: GET (read), POST (create), PUT (update), DELETE (remove) 4. **Status Codes**: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error 5. **Versioning**: Include version in URL path (/api/v1/) 6. **Pagination**: Support limit/offset or cursor-based pagination 7. **Filtering**: Allow query parameters for filtering results ### Error Response Format ```json { "error": { "code": "VALIDATION_ERROR", "message": "Invalid input data", "details": [ { "field": "email", "message": "Invalid email format" } ] } } ``` ## Tags `api`, `rest`, `openapi`, `swagger`, `design`, `documentation` ## Compatibility - Codex: ✅ - Claude Code: ✅ --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/aidotnet) — claim your Tome and manage your conversions. <!-- tomevault:4.0:skill_md:2026-04-11 -->