Api Development Expert
When designing REST APIs, follow these core architectural principles:
Resource-Oriented Design
Use nouns for resources (plural form): /users, /products, /orders Avoid verbs in URIs: ❌ /getUsers, /createProduct Structure hierarchically: /users/{userId}/orders (orders belonging to a user) Use lowercase with hyphens: /product-details not /productdetails No trailing slashes: /users not /users/
HTTP Methods (Verbs with Purpose)
GET - Retrieve resources (idempotent & safe, no side effects) POST - Create new resources (not idempotent, returns 201 Created with Location header) PUT - Replace entire resource or upsert (idempotent) PATCH - Partial update (not idempotent, use application/json-patch+json) DELETE - Remove resource (idempotent, returns 204 No Content or 200 OK)
Query Parameters for Filtering, Sorting, and Pagination
Filtering: /products?category=electronics&price_gt=100 Sorting: /products?sort_by=price&order=desc Pagination: /products?page=2&limit=10 Use offset-based (simple but inefficient for deep pages) or cursor-based (efficient for large datasets) API Versioning Strategies
Choose one and stick to it:
URI Versioning (Most common): /v1/users, /api/v2/products Simple for clients, but makes URIs less clean Header Versioning: Accept: application/vnd.myapi.v1+json Cleaner URIs, but slightly complex for caching and some clients Content Negotiation: Use Accept header to specify desired media type and version OpenAPI/Swagger Specification
Use OpenAPI 3.0+ to define your API specification:
Benefits:
Machine-readable API specification Auto-generates interactive documentation portals Client SDK generation Request/response schema validation IDE and API tool auto-validation
Define schemas for:
Request parameters (required fields, allowed values, data types) Response structures Error responses Authentication methods Enum lists for restricted values
Example: Define validation rules so invalid requests are caught before reaching your backend
Rate Limiting Patterns
Protect against abuse and ensure fair usage:
Implementation strategies:
Use 429 Too Many Requests status code Return rate limit headers: X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640000000 Common patterns: Fixed window: Simple but allows bursts at boundaries Sliding window: More accurate, prevents boundary gaming Token bucket: Allows controlled bursts Leaky bucket: Smooths out traffic Error Handling Standards
Consistent Error Response Structure:
{ "error": { "code": "validation_error", "message": "Input validation failed.", "details": [{ "field": "email", "message": "Invalid email format." }] } }
Use Appropriate HTTP Status Codes:
2xx Success: 200 OK, 201 Created, 204 No Content
3xx Redirection: 301 Moved Permanently, 304 Not Modified
4xx Client Error:
400 Bad Request - General client error 401 Unauthorized - Authentication missing/failed 403 Forbidden - Authenticated but no permission 404 Not Found - Resource doesn't exist 405 Method Not Allowed - Invalid HTTP method 409 Conflict - Resource already exists 422 Unprocessable Entity - Semantic validation error 429 Too Many Requests - Rate limiting
5xx Server Error:
500 Internal Server Error - Generic server error 503 Service Unavailable - Service temporarily down
Provide machine-readable codes AND human-readable messages
Authentication Patterns
OAuth 2.1 (Industry standard for delegated authorization)
Mandatory PKCE for all authorization code flows Authorization Code + PKCE flow for SPAs, mobile, and web apps Removed flows: Implicit grant and Resource Owner Password Credentials (security risks) Exact redirect URI matching (no wildcards) Never send bearer tokens in query strings (use Authorization header) Implement refresh token rotation or sender-constrained tokens
JWT (JSON Web Tokens) for stateless authentication:
Short expiry times (≤15 minutes for access tokens) Use refresh tokens for long-lived sessions Include claims for authorization decisions Validate signature, expiry, and issuer
API Keys for simpler integrations:
Use for service-to-service authentication Rotate regularly Never expose in client-side code Implement rate limiting per key Performance & Caching
HTTP Caching Headers:
Cache-Control: max-age=3600 - Cache for 1 hour ETag - Entity tag for conditional requests Expires - Absolute expiration time 304 Not Modified - Return for unchanged resources
Caching strategies:
Client-side caching (browser cache) Proxy/CDN caching (intermediate caches) Server-side caching (database query cache, object cache)
Optimization techniques:
Compression: Use GZIP for large responses Pagination: Return only needed data Field selection: Allow clients to request specific fields (?fields=id,name) Async operations: For long-running tasks, return 202 Accepted with status endpoint API Documentation Best Practices
Comprehensive documentation must include:
Overview and getting started guide Authentication and authorization details Endpoint descriptions with HTTP methods Request parameters and body schemas Response structures with examples Error codes and messages Rate limits and usage policies SDKs and client libraries Changelog for version updates
Use tools:
Swagger UI / OpenAPI for interactive docs Postman collections for testing Code examples in multiple languages Consolidated Skills
This expert skill consolidates 1 individual skills:
api-development-expert Memory Protocol (MANDATORY)
Before starting:
cat .claude/context/memory/learnings.md
After completing: Record any new patterns or exceptions discovered.
ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.