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:

• Design Endpoints: Create RESTful endpoints following naming conventions

• Define Schemas: Create request/response JSON schemas

• Generate OpenAPI: Produce OpenAPI 3.0+ specifications

• Document: Provide comprehensive API documentation

Instructions

When designing an API:

Analyze Requirements:

• What resources need to be exposed?

• What operations are needed (CRUD, custom actions)?

• What authentication is required?

• What are the data relationships?

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

Define Request/Response Schemas:

{ "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"] }

Generate OpenAPI Specification:

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

• Resource-Oriented: Design around resources, not actions

• Consistent Naming: Use plural nouns for collections

• Proper HTTP Methods: GET (read), POST (create), PUT (update), DELETE (remove)

• Status Codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error

• Versioning: Include version in URL path (/api/v1/)

• Pagination: Support limit/offset or cursor-based pagination

• Filtering: Allow query parameters for filtering results

Error Response Format

{ "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: ✅