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.