api-design

---
name: api-design
description: >
  RESTful and GraphQL API design skill with endpoint patterns, request/response
  schemas, versioning, pagination, filtering, error handling, and API documentation.
license: MIT
---

# API Design Skill — Professional API Patterns

This skill provides comprehensive API design guidance following industry best practices.

## RESTful API Standards

### URL Structure

```
GET    /api/v1/resources              # List (paginated, filtered)
GET    /api/v1/resources/:id          # Detail (with includes)
POST   /api/v1/resources              # Create
PATCH  /api/v1/resources/:id          # Partial update
PUT    /api/v1/resources/:id          # Full replace
DELETE /api/v1/resources/:id          # Delete (soft by default)
POST   /api/v1/resources/:id/restore  # Restore soft-deleted
```

### Response Envelope

```typescript
// Success - Single
{ data: { ... }, meta: { requestId, timestamp } }

// Success - Collection
{
  data: [...],
  meta: { requestId, timestamp },
  pagination: {
    page: 1,
    perPage: 20,
    total: 150,
    totalPages: 8,
    hasNext: true,
    hasPrev: false
  }
}

// Error
{
  error: {
    code: "VALIDATION_ERROR",
    message: "Human-readable message",
    details: [
      { field: "email", message: "Invalid email format" }
    ]
  },
  meta: { requestId, timestamp }
}
```

### Filtering & Sorting

```
GET /api/v1/products?
  filter[category]=electronics&
  filter[price_min]=10&
  filter[price_max]=100&
  filter[status]=active&
  sort=-createdAt,name&
  page=2&
  perPage=50&
  include=category,variants
```

### HTTP Status Codes

| Code | Usage                                          |
| ---- | ---------------------------------------------- |
| 200  | Success (GET, PATCH, PUT, DELETE)              |
| 201  | Created (POST)                                 |
| 204  | No Content (successful DELETE with no body)    |
| 400  | Validation Error                               |
| 401  | Unauthorized (missing/invalid auth)            |
| 403  | Forbidden (insufficient permissions)           |
| 404  | Not Found                                      |
| 409  | Conflict (duplicate, version mismatch)         |
| 422  | Unprocessable Entity (business rule violation) |
| 429  | Too Many Requests (rate limiting)              |
| 500  | Internal Server Error                          |

### Versioning Strategy

```
URL Versioning (recommended for REST):
  /api/v1/resources
  /api/v2/resources

Header Versioning (alternative):
  Accept: application/vnd.api.v1+json
```

## CRUD Completeness for API

Every resource MUST have these endpoints:

```typescript
// 1. CREATE - Full validation
POST /api/v1/products
Body: { name, sku, price, categoryId, ... }
Response: 201 { data: product }

// 2. READ LIST - Paginated with filters
GET /api/v1/products?filter[status]=active&sort=-createdAt
Response: 200 { data: [...], pagination: {...} }

// 3. READ DETAIL - With relationships
GET /api/v1/products/:id?include=category,variants
Response: 200 { data: product }

// 4. UPDATE - Partial update
PATCH /api/v1/products/:id
Body: { price: 29.99 }
Response: 200 { data: product }

// 5. DELETE - Soft delete
DELETE /api/v1/products/:id
Response: 200 { data: { deleted: true } }

// 6. RESTORE - If soft delete
POST /api/v1/products/:id/restore
Response: 200 { data: product }
```

## Rate Limiting

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000
```

## API Documentation Standard

Every endpoint must document:

1. Description and purpose
2. Required permissions/roles
3. Request body schema (with examples)
4. Response schema (success + all error codes)
5. Query parameters (filter, sort, include, pagination)
6. Rate limit information

## When NOT to Use

**Do NOT use this skill when:**

- Designing database schemas (use database-design skill for table structures and relationships)
- Writing application business logic (use domain-driven skill for complete business modules)
- Reviewing existing code for quality issues (use code-review skill for comprehensive audits)
- Performing security audits on APIs (use security-auditor skill for vulnerability analysis)
- Writing SQL queries for data access (use sql-best-practices skill for query optimization)
- **Designing multi-page website layouts** (use design-system skill for professional UI/UX and spacing)
- **Analyzing deployment configurations** (use deployment skill for CI/CD and infrastructure)
- **Reviewing git workflows** (use git-workflow skill for branching and commit conventions)
- **Implementing third-party integrations** (use third-party-integrations skill for external services)