API Patterns Toolkit

A Claude Code skill covering modern API design principles and decision-making frameworks for building robust, scalable APIs. Teaches you to think about API design rather than copy fixed patterns — covering REST conventions, versioning, error handling, pagination, authentication, and rate limiting.

When to Use This Skill

Choose API Patterns Toolkit when:

• You're designing a new API and want to follow modern best practices
• You need to make design decisions about pagination, versioning, or error formats
• You want to review an existing API design for consistency and standards
• You need to choose between REST, GraphQL, and gRPC for your use case
• You want a reference for common API design patterns and anti-patterns

Consider alternatives when:

• You need to generate API documentation (use an API documentation skill)
• You want to integrate with external APIs (use an API integration skill)
• You need specific framework implementation (use a framework-specific skill)

Quick Start

Copy
# Install the skill
claude install api-patterns-toolkit

# Design an API
claude "Design a REST API for a task management app: CRUD for tasks, projects, and team members with proper resource relationships"

# Choose pagination strategy
claude "Should I use cursor-based or offset pagination for my API? We expect 100K+ records in some collections"

# Design error responses
claude "Design a consistent error response format for my API that handles validation errors, auth errors, and server errors"

Core Concepts

API Style Selection

Style	Best For	Trade-offs
REST	CRUD-heavy, public APIs, simple resources	Over/under-fetching, multiple round trips
GraphQL	Complex data requirements, mobile clients	Schema complexity, caching difficulty
gRPC	Service-to-service, high performance	Browser support, tooling, learning curve
WebSocket	Real-time, bidirectional communication	Connection management, scaling

REST Design Principles

URL Structure:
  /api/v1/users              → Collection
  /api/v1/users/:id          → Single resource
  /api/v1/users/:id/projects → Nested resource

HTTP Methods:
  GET    → Read (idempotent, cacheable)
  POST   → Create (not idempotent)
  PUT    → Full replace (idempotent)
  PATCH  → Partial update (idempotent)
  DELETE → Remove (idempotent)

Status Codes:
  200 → Success (with body)
  201 → Created (with Location header)
  204 → Success (no body, for DELETE)
  400 → Client error (validation)
  401 → Not authenticated
  403 → Not authorized
  404 → Not found
  409 → Conflict
  429 → Rate limited
  500 → Server error

Pagination Patterns

Pattern	Pros	Cons	Best For
Offset/Limit	Simple, supports random access	Slow on large datasets, inconsistent with inserts	Small datasets, admin panels
Cursor-Based	Consistent, fast at any depth	No random access, complex implementation	Feeds, timelines, large datasets
Keyset	Fast, stable ordering	Requires unique sortable column	Sorted lists, analytics

Configuration

Parameter	Type	Default	Description
api_style	string	"rest"	Style: rest, graphql, grpc
versioning	string	"url"	Versioning: url (/v1/), header, query
auth_method	string	"bearer"	Auth: bearer, api_key, oauth2, session
pagination	string	"cursor"	Pagination: cursor, offset, keyset
error_format	string	"rfc7807"	Error format: rfc7807, custom, simple

Best Practices

1. Use nouns for resources, not verbs — /api/users not /api/getUsers. HTTP methods already express the action. Verbs in URLs are a sign of RPC thinking, not REST. The one exception: non-CRUD operations like /api/users/:id/activate.

2. Version your API from day one — Even if you only have v1, include the version in the URL (/api/v1/). Changing this later requires migrating all clients. URL-based versioning is the simplest and most visible approach.

3. Use consistent error responses — Every error should return the same JSON structure with at minimum: status code, error type, and human-readable message. Include a machine-readable error code for client-side handling.

4. Default to cursor-based pagination — Offset pagination breaks on large datasets and produces inconsistent results when data changes between pages. Cursor-based pagination is consistent and performs well at any depth.

5. Rate limit everything — Even internal APIs need rate limiting to prevent accidental abuse. Return rate limit info in headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and use 429 status codes.

Common Issues

API response is too large — Implement sparse fieldsets (allow clients to specify which fields to return) and pagination. Don't return nested resources by default — let clients request them with query parameters like ?include=comments.

Breaking changes after release — Use additive changes (new fields, new endpoints) whenever possible. When breaking changes are unavoidable, version the API and maintain the old version for a deprecation period.

Inconsistent naming across endpoints — Establish naming conventions early: camelCase vs snake_case for JSON keys, plural vs singular for resources, past tense vs present for event names. Document and enforce them.