API Development Patterns

Master API development with Cursor IDE and Claude Code. These patterns cover REST, GraphQL, gRPC, API design principles, versioning strategies, security, documentation, and testing approaches optimized for AI-assisted development.

API Design Fundamentals

RESTful API Design

Cursor IDE

1. Open Cursor in your project
2. Activate Agent mode (Cmd/Ctrl + I)
3. Prompt: “Design RESTful API for task management with:
   • Resource-based URLs
   • Proper HTTP methods
   • Status codes
   • HATEOAS links
   • Pagination
   • Filtering and sorting”
4. Agent creates complete API specification

Claude Code

1. Run: claude "Create OpenAPI 3.0 specification for e-commerce API"
2. Claude will design:
   • RESTful endpoints
   • Request/response schemas
   • Authentication methods
   • Error handling standards

REST API Patterns

Resource Design

# API design prompt:
"Design REST resources for blog platform:
- Hierarchical resources (/blogs/{id}/posts/{id}/comments)
- Resource relationships
- Consistent naming conventions
- Action endpoints for non-CRUD
- Bulk operations
- Async operations with status endpoints"

Advanced REST Features

Hypermedia

// Prompt: "Add HATEOAS links:
// - Resource navigation
// - Available actions
// - Related resources
// - Pagination links"

Content Negotiation

# Prompt: "Implement content negotiation:
# - Multiple response formats
# - Language selection
# - Version negotiation
# - Compression support"

Tip

When designing REST APIs, ask AI to follow REST maturity model level 3 (HATEOAS) for maximum flexibility and discoverability.

GraphQL API Patterns

Schema Design

# GraphQL schema prompt:
"Design GraphQL schema for social network:
- User types with relationships
- Query complexity limiting
- Dataloader for N+1 prevention
- Subscription for real-time updates
- Custom scalars
- Federation support"

Resolver Patterns

Query Optimization

// Resolver optimization prompt:
"Optimize GraphQL resolvers with:
- Batch loading
- Caching strategies
- Query depth limiting
- Field-level permissions
- Error handling"

Mutations

// Mutation patterns:
"Implement mutations with:
- Input validation
- Optimistic updates
- Error types
- Side effects handling
- Event emission"

gRPC Patterns

Service Definition

// gRPC service prompt:
"Create gRPC service for payment processing:
- Protocol buffer definitions
- Service methods (unary, streaming)
- Error handling with status codes
- Interceptors for auth/logging
- Health checking
- Load balancing support"

Advanced gRPC Features

1. Streaming: “Implement bidirectional streaming for chat”
2. Interceptors: “Add auth and logging interceptors”
3. Error Handling: “Create rich error details”
4. Performance: “Optimize with connection pooling”

API Versioning

Versioning Strategies

// Versioning implementation prompt:
"Implement API versioning with:
- URL versioning (/v1/, /v2/)
- Header versioning
- Content negotiation
- Sunset headers
- Migration guides
- Backward compatibility"

Version Management

AI can help with:

• Deprecation strategies
• Version migration paths
• Feature flags for gradual rollout
• Client compatibility detection
• Documentation updates

Authentication & Authorization

OAuth 2.0 Implementation

// OAuth implementation prompt:
"Implement OAuth 2.0 with:
- Authorization code flow
- Refresh token rotation
- PKCE for public clients
- Scope management
- Token introspection
- Revocation endpoints"

API Security Patterns

JWT

// JWT implementation:
"Set up JWT auth with:
- Token generation
- Claims validation
- Refresh strategy
- Blacklisting
- Key rotation"

API Keys

// API key system:
"Create API key management:
- Key generation
- Rate limiting per key
- Scope restrictions
- Usage analytics
- Key rotation"

Rate Limiting & Throttling

Implementation Strategies

// Rate limiting prompt:
"Implement rate limiting with:
- Token bucket algorithm
- Sliding window counters
- Distributed rate limiting
- User-based limits
- Endpoint-specific limits
- Graceful degradation"

Caution

Always implement rate limiting headers (X-RateLimit-*) to help clients manage their request patterns effectively.

API Documentation

OpenAPI/Swagger

# Documentation prompt:
"Generate OpenAPI documentation with:
- Complete schema definitions
- Request/response examples
- Authentication details
- Error responses
- Webhook specifications
- Testing endpoints"

Documentation Best Practices

Interactive Docs

// Prompt: "Create Swagger UI with:
// - Try-it-out functionality
// - Code generation
// - Multiple languages
// - Environment switching"

SDK Generation

// Prompt: "Generate client SDKs:
// - TypeScript/JavaScript
// - Python
// - Go
// - Java
// With proper error handling"

Error Handling

Consistent Error Responses

// Error handling prompt:
"Design error response format:
{
  'error': {
    'code': 'RESOURCE_NOT_FOUND',
    'message': 'User not found',
    'details': {...},
    'timestamp': '2024-01-01T00:00:00Z',
    'traceId': 'abc123'
  }
}

Include:
- Standard error codes
- Localized messages
- Debug information
- Recovery suggestions"

Pagination Patterns

Pagination Strategies

Offset-Based

# Offset pagination:
"Implement offset pagination:
- Page and limit parameters
- Total count in response
- Link headers
- Max limit enforcement"

Cursor-Based

# Cursor pagination:
"Implement cursor pagination:
- Opaque cursor tokens
- Stable sorting
- Efficient queries
- Bidirectional navigation"

Webhooks & Events

Webhook Implementation

// Webhook system prompt:
"Create webhook system with:
- Event registration
- Payload signing
- Retry logic
- Dead letter queue
- Event filtering
- Delivery tracking"

1. Design Events: “Define event schema and types”
2. Implement Delivery: “Create reliable delivery system”
3. Add Security: “Implement HMAC signature verification”
4. Monitor Health: “Track delivery success rates”

API Testing

Comprehensive Testing

// API testing prompt:
"Create API test suite with:
- Contract testing
- Integration tests
- Load testing
- Security testing
- Mock services
- Test data management"

Testing Strategies

Test Automation

AI can generate:

• Postman collections
• Newman CI integration
• Pact contract tests
• K6 performance tests
• Security scan configs

Caching Strategies

HTTP Caching

# Caching implementation:
"Implement HTTP caching with:
- ETag generation
- Cache-Control headers
- Conditional requests
- CDN integration
- Cache invalidation
- Vary headers"

Monitoring & Analytics

API Observability

// Monitoring prompt:
"Set up API monitoring with:
- Request/response logging
- Performance metrics
- Error tracking
- Usage analytics
- SLA monitoring
- Alerting rules"

Tip

Implement correlation IDs across all API requests to enable effective distributed tracing and debugging.

API Gateway Patterns

Gateway Implementation

# API gateway prompt:
"Configure API gateway for:
- Request routing
- Authentication
- Rate limiting
- Request/response transformation
- Circuit breaking
- Service discovery"

Best Practices with AI

Effective API Prompts

// Structure prompts like:
"Design [REST/GraphQL/gRPC] API for [domain] with:
- Use cases: [list specific operations]
- Performance requirements: [SLA]
- Security needs: [auth method]
- Integration points: [external services]
- Include examples and edge cases"

API Design Review

Design Review

AI can review for:

• RESTful principles
• Security vulnerabilities
• Performance issues
• Documentation gaps

Code Generation

AI can generate:

• API clients
• Server stubs
• Test suites
• Documentation

Advanced Patterns

Event-Driven APIs

// Event-driven API:
"Implement event-driven API with:
- Server-sent events
- WebSocket support
- Event sourcing
- CQRS pattern
- Event replay
- Schema registry"

API Composition

// API composition pattern:
"Create API composition layer:
- Backend for frontend (BFF)
- Service aggregation
- Response transformation
- Fallback strategies
- Cache coordination"

Next Steps

• Explore Serverless patterns for API deployment
• Learn Testing patterns for API testing
• Master DevOps patterns for API operations