---
name: api-design
description: REST/GraphQL API design patterns, authentication, versioning, error handling. Use when designing or reviewing APIs.
---

# API Design Skill

## REST Conventions
| Method | Endpoint | Action |
|--------|----------|--------|
| GET | /api/items | List all |
| GET | /api/items/:id | Get one |
| POST | /api/items | Create |
| PUT | /api/items/:id | Full update |
| PATCH | /api/items/:id | Partial update |
| DELETE | /api/items/:id | Delete |

## Response Format
```json
{
  "data": { "id": 1, "name": "Item" },
  "meta": { "total": 100, "page": 1 },
  "errors": null
}
```

## Error Responses
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {"field": "email", "message": "Must be valid"}
    ]
  }
}
```

## HTTP Status Codes
- **200** OK - Successful GET/PUT/PATCH
- **201** Created - Successful POST
- **204** No Content - Successful DELETE
- **400** Bad Request - Validation error
- **401** Unauthorized - Not authenticated
- **403** Forbidden - Not authorized
- **404** Not Found - Resource doesn't exist
- **409** Conflict - Duplicate resource
- **422** Unprocessable - Business logic error
- **500** Internal Error - Server fault

## Authentication
```
Authorization: Bearer <jwt_token>
```

## Versioning
```
/api/v1/users     # URL path versioning (recommended)
Accept: application/vnd.api.v1+json  # Header versioning
```

## Rate Limiting Headers
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
```
