api-design-patterns

What this skill does

# API Design Patterns

RESTful API design principles for building consistent, developer-friendly APIs. Contains 38 rules across 7 categories covering resource design, error handling, security, pagination, versioning, response format, and documentation.

## Metadata

- **Version:** 2.0.0
- **Rule Count:** 38 rules across 7 categories
- **License:** MIT

## When to Apply

Reference these guidelines when:
- Designing new API endpoints
- Reviewing existing API structure
- Implementing error handling and validation
- Setting up pagination, filtering, and sorting
- Planning API versioning strategy
- Configuring API security (auth, CORS, rate limiting)
- Writing API documentation (OpenAPI/Swagger)

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Resource Design | CRITICAL | `rest-` |
| 2 | Error Handling | CRITICAL | `error-` |
| 3 | Security | CRITICAL | `sec-` |
| 4 | Pagination & Filtering | HIGH | `page-`, `filter-`, `sort-` |
| 5 | Versioning | HIGH | `ver-` |
| 6 | Response Format | MEDIUM | `resp-` |
| 7 | Documentation | MEDIUM | `doc-` |

## Quick Reference

### 1. Resource Design (CRITICAL)

- `rest-nouns-not-verbs` - Use nouns for endpoints, not verbs
- `rest-plural-resources` - Use plural resource names
- `rest-http-methods` - Correct HTTP method usage (GET, POST, PUT, PATCH, DELETE)
- `rest-nested-resources` - Proper resource nesting (max 2 levels)
- `rest-status-codes` - Appropriate HTTP status codes
- `rest-idempotency` - Idempotent operations with idempotency keys
- `rest-hateoas` - Hypermedia links for discoverability
- `rest-resource-actions` - Non-CRUD actions as sub-resources

### 2. Error Handling (CRITICAL)

- `error-consistent-format` - Consistent error response structure
- `error-meaningful-messages` - Helpful, actionable error messages
- `error-validation-details` - Field-level validation errors
- `error-error-codes` - Machine-readable error codes
- `error-no-stack-traces` - Never expose stack traces in production
- `error-request-id` - Include request IDs for debugging

### 3. Security (CRITICAL)

- `sec-authentication` - Proper auth implementation (OAuth2/JWT)
- `sec-authorization` - Resource-level permissions (RBAC)
- `sec-rate-limiting` - Prevent abuse with rate limiting
- `sec-input-validation` - Validate and sanitize all input
- `sec-cors-config` - CORS configuration with whitelists
- `sec-https-only` - Enforce HTTPS for all traffic
- `sec-sensitive-data` - Protect passwords, tokens, PII

### 4. Pagination & Filtering (HIGH)

- `page-cursor-based` - Cursor pagination for large datasets
- `page-offset-based` - Offset pagination for simple cases
- `page-consistent-params` - Consistent parameter naming
- `page-metadata` - Include pagination metadata in responses
- `filter-query-params` - Filter via query parameters
- `sort-flexible` - Flexible sorting with `-` prefix for descending

### 5. Versioning (HIGH)

- `ver-url-path` - Version in URL path (/api/v1/)
- `ver-header-based` - Version via Accept header
- `ver-backward-compatible` - Maintain backward compatibility
- `ver-deprecation` - Deprecation strategy with Sunset header

### 6. Response Format (MEDIUM)

- `resp-consistent-structure` - Consistent response envelope
- `resp-json-conventions` - JSON naming conventions
- `resp-partial-responses` - Field selection (sparse fieldsets)
- `resp-compression` - Response compression (gzip/Brotli)

### 7. Documentation (MEDIUM)

- `doc-openapi` - OpenAPI/Swagger specification
- `doc-examples` - Request/response examples
- `doc-changelog` - API changelog

## Essential Guidelines

### Resource Naming

```
# ❌ Verbs in URLs
GET    /getUsers
POST   /createUser

# ✅ Nouns with HTTP methods
GET    /users          # List users
POST   /users          # Create user
GET    /users/123      # Get user
PUT    /users/123      # Update user (full)
PATCH  /users/123      # Update user (partial)
DELETE /users/123      # Delete user
```

### Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Please provide a valid email address"
      }
    ],
    "request_id": "req_abc123"
  }
}
```

### Pagination

```json
{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total_pages": 10,
    "total_count": 195
  },
  "links": {
    "first": "/users?page=1&per_page=20",
    "prev": "/users?page=1&per_page=20",
    "next": "/users?page=3&per_page=20",
    "last": "/users?page=10&per_page=20"
  }
}
```

### Rate Limiting Headers

```
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1640995200
```

## How to Use

Read individual rule files for detailed explanations:

```
rules/rest-http-methods.md
rules/error-consistent-format.md
rules/page-cursor-based.md
rules/sec-authentication.md
rules/ver-url-path.md
rules/doc-openapi.md
```

## References

- [RESTful API Guidelines](https://restfulapi.net)
- [Zalando RESTful API Guidelines](https://zalando.github.io/restful-api-guidelines)
- [Microsoft API Guidelines](https://github.com/microsoft/api-guidelines)
- [Google API Design Guide](https://cloud.google.com/apis/design)
- [OpenAPI Specification](https://swagger.io/specification)

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`