API Design Reviewer

API Design Reviewer

Tier: POWERFUL Category: Engineering / Architecture Maintainer: Claude Skills Team

Overview

The API Design Reviewer skill provides comprehensive analysis and review of API designs, focusing on REST conventions, best practices, and industry standards. This skill helps engineering teams build consistent, maintainable, and well-designed APIs through automated linting, breaking change detection, and design scorecards.

1. API Linting and Convention Analysis

Resource Naming Conventions: Enforces kebab-case for resources, camelCase for fields HTTP Method Usage: Validates proper use of GET, POST, PUT, PATCH, DELETE URL Structure: Analyzes endpoint patterns for consistency and RESTful design Status Code Compliance: Ensures appropriate HTTP status codes are used Error Response Formats: Validates consistent error response structures Documentation Coverage: Checks for missing descriptions and documentation gaps

2. Breaking Change Detection

Endpoint Removal: Detects removed or deprecated endpoints Response Shape Changes: Identifies modifications to response structures Field Removal: Tracks removed or renamed fields in API responses Type Changes: Catches field type modifications that could break clients Required Field Additions: Flags new required fields that could break existing integrations Status Code Changes: Detects changes to expected status codes

3. API Design Scoring and Assessment

Consistency Analysis (30%): Evaluates naming conventions, response patterns, and structural consistency Documentation Quality (20%): Assesses completeness and clarity of API documentation Security Implementation (20%): Reviews authentication, authorization, and security headers Usability Design (15%): Analyzes ease of use, discoverability, and developer experience Performance Patterns (15%): Evaluates caching, pagination, and efficiency patterns

Resource Naming Conventions

• ✅ Good Examples:
• /api/v1/users
• /api/v1/user-profiles
• /api/v1/orders/123/line-items
• ❌ Bad Examples:
• /api/v1/getUsers
• /api/v1/user_profiles
• /api/v1/orders/123/lineItems

HTTP Method Usage

GET: Retrieve resources (safe, idempotent) POST: Create new resources (not idempotent) PUT: Replace entire resources (idempotent) PATCH: Partial resource updates (not necessarily idempotent) DELETE: Remove resources (idempotent)

URL Structure Best Practices

Collection Resources: /api/v1/users Individual Resources: /api/v1/users/123 Nested Resources: /api/v1/users/123/orders Actions: /api/v1/users/123/activate (POST) Filtering: /api/v1/users?status=active&role=admin

1. URL Versioning (Recommended)

/api/v1/users /api/v2/users Pros: Clear, explicit, easy to route Cons: URL proliferation, caching complexity

2. Header Versioning

GET /api/users Accept: application/vnd.api+json;version=1 Pros: Clean URLs, content negotiation Cons: Less visible, harder to test manually

3. Media Type Versioning

GET /api/users Accept: application/vnd.myapi.v1+json Pros: RESTful, supports multiple representations Cons: Complex, harder to implement

4. Query Parameter Versioning

/api/users?version=1 Pros: Simple to implement Cons: Not RESTful, can be ignored

Offset-Based Pagination

{ "data": [...], "pagination": { "offset": 20, "limit": 10, "total": 150, "hasMore": true } }

Cursor-Based Pagination

{ "data": [...], "pagination": { "nextCursor": "eyJpZCI6MTIzfQ==", "hasMore": true } }

Page-Based Pagination

{ "data": [...], "pagination": { "page": 3, "pageSize": 10, "totalPages": 15, "totalItems": 150 } }

Standard Error Structure

{ "error": { "code": "VALIDATION_ERROR", "message": "The request contains invalid parameters", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email address is not valid" } ], "requestId": "req-123456", "timestamp": "2024-02-16T13:00:00Z" } }

HTTP Status Code Usage

400 Bad Request: Invalid request syntax or parameters 401 Unauthorized: Authentication required 403 Forbidden: Access denied (authenticated but not authorized) 404 Not Found: Resource not found 409 Conflict: Resource conflict (duplicate, version mismatch) 422 Unprocessable Entity: Valid syntax but semantic errors 429 Too Many Requests: Rate limit exceeded 500 Internal Server Error: Unexpected server error

Bearer Token Authentication

Authorization: Bearer <token>

API Key Authentication

X-API-Key: <api-key> Authorization: Api-Key <api-key>

OAuth 2.0 Flow

Authorization: Bearer <oauth-access-token>

Role-Based Access Control (RBAC)

{ "user": { "id": "123", "roles": ["admin", "editor"], "permissions": ["read:users", "write:orders"] } }

Headers

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640995200

Response on Limit Exceeded

{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests", "retryAfter": 3600 } }

Example Implementation

{ "id": "123", "name": "John Doe", "email": "john@example.com", "_links": { "self": { "href": "/api/v1/users/123" }, "orders": { "href": "/api/v1/users/123/orders" }, "profile": { "href": "/api/v1/users/123/profile" }, "deactivate": { "href": "/api/v1/users/123/deactivate", "method": "POST" } } }

Idempotent Methods

GET: Always safe and idempotent PUT: Should be idempotent (replace entire resource) DELETE: Should be idempotent (same result) PATCH: May or may not be idempotent

Idempotency Keys

POST /api/v1/payments Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

Safe Changes (Non-Breaking)

Adding optional fields to requests Adding fields to responses Adding new endpoints Making required fields optional Adding new enum values (with graceful handling)

Breaking Changes (Require Version Bump)

Removing fields from responses Making optional fields required Changing field types Removing endpoints Changing URL structures Modifying error response formats

Required Components

API Information: Title, description, version Server Information: Base URLs and descriptions Path Definitions: All endpoints with methods Parameter Definitions: Query, path, header parameters Request/Response Schemas: Complete data models Security Definitions: Authentication schemes Error Responses: Standard error formats

Best Practices

Use consistent naming conventions Provide detailed descriptions for all components Include examples for complex objects Define reusable components and schemas Validate against OpenAPI specification

Caching Strategies

Cache-Control: public, max-age=3600 ETag: "123456789" Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

Efficient Data Transfer

Use appropriate HTTP methods Implement field selection (?fields=id,name,email) Support compression (gzip) Implement efficient pagination Use ETags for conditional requests

Resource Optimization

Avoid N+1 queries Implement batch operations Use async processing for heavy operations Support partial updates (PATCH)

Input Validation

Validate all input parameters Sanitize user data Use parameterized queries Implement request size limits

Authentication Security

Use HTTPS everywhere Implement secure token storage Support token expiration and refresh Use strong authentication mechanisms

Authorization Controls

Implement principle of least privilege Use resource-based permissions Support fine-grained access control Audit access patterns

api_linter.py

Analyzes API specifications for compliance with REST conventions and best practices. Features: OpenAPI/Swagger spec validation Naming convention checks HTTP method usage validation Error format consistency Documentation completeness analysis

breaking_change_detector.py

Compares API specification versions to identify breaking changes. Features: Endpoint comparison Schema change detection Field removal/modification tracking Migration guide generation Impact severity assessment

api_scorecard.py

Provides comprehensive scoring of API design quality. Features: Multi-dimensional scoring Detailed improvement recommendations Letter grade assessment (A-F) Benchmark comparisons Progress tracking

CI/CD Integration

• name: "api-linting"
• run: python scripts/api_linter.py openapi.json
• name: "breaking-change-detection"
• run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json
• name: "api-scorecard"
• run: python scripts/api_scorecard.py openapi.json

Pre-commit Hooks

#!/bin/bash python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json if [ $? -ne 0 ]; then echo "API linting failed. Please fix the issues before committing." exit 1 fi

Best Practices Summary

Consistency First: Maintain consistent naming, response formats, and patterns Documentation: Provide comprehensive, up-to-date API documentation Versioning: Plan for evolution with clear versioning strategies Error Handling: Implement consistent, informative error responses Security: Build security into every layer of the API Performance: Design for scale and efficiency from the start Backward Compatibility: Minimize breaking changes and provide migration paths Testing: Implement comprehensive testing including contract testing Monitoring: Add observability for API usage and performance Developer Experience: Prioritize ease of use and clear documentation

Common Anti-Patterns to Avoid

Verb-based URLs: Use nouns for resources, not actions Inconsistent Response Formats: Maintain standard response structures Over-nesting: Avoid deeply nested resource hierarchies Ignoring HTTP Status Codes: Use appropriate status codes for different scenarios Poor Error Messages: Provide actionable, specific error information Missing Pagination: Always paginate list endpoints No Versioning Strategy: Plan for API evolution from day one Exposing Internal Structure: Design APIs for external consumption, not internal convenience Missing Rate Limiting: Protect your API from abuse and overload Inadequate Testing: Test all aspects including error cases and edge conditions

Conclusion

The API Design Reviewer skill provides a comprehensive framework for building, reviewing, and maintaining high-quality REST APIs. By following these guidelines and using the provided tools, development teams can create APIs that are consistent, well-documented, secure, and maintainable. Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle.