api-design

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

Method	Use Case	Idempotent
GET	Retrieve resource	Yes
POST	Create resource	No
PUT	Replace resource	Yes
PATCH	Partial update	No
DELETE	Remove resource	Yes

URL Patterns

GET    /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

Code	Meaning	Use When
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Validation error
401	Unauthorized	Auth required
403	Forbidden	Auth insufficient
404	Not Found	Resource doesn't exist
422	Unprocessable	Business rule violation
500	Server Error	Unexpected error

Error Response Format

Reference: standards/error-responses.md

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