---

name: api-design description: Design RESTful APIs following conventions with proper error handling, versioning, and documentation. Use when creating or modifying API endpoints.

API Design Skill

Purpose

Create consistent, well-designed APIs.

REST Conventions

Reference: standards/rest-conventions.md

HTTP Methods

URL Patterns

CopyGET    /users           # List users
GET    /users/:id       # Get user
POST   /users           # Create user
PUT    /users/:id       # Replace user
PATCH  /users/:id       # Update user
DELETE /users/:id       # Delete user

GET    /users/:id/posts # Nested resource

Response Status Codes

Error Response Format

Reference: standards/error-responses.md

Copy{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Versioning

Reference: standards/versioning.md

Options:

• URL: /api/v1/users
• Header: Accept: application/vnd.api.v1+json

Recommendation: URL versioning for simplicity

Endpoint Documentation

Use template: templates/endpoint-doc.md