API Design Reviewer

What This Skill Does

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

When to Use

• Lint API designs for REST conventions.
• Detect breaking changes in API updates.
• Score API designs for consistency and quality.
• Enforce resource naming and HTTP method usage.
• Validate error response formats.
• Check for missing documentation and descriptions.

Key Features

• Enforces resource naming and HTTP method usage.
• Detects removed endpoints and response shape changes.
• Identifies field removals and type changes.
• Assesses consistency, documentation, security, usability, and performance.
• Provides API linting and convention analysis.
• Offers API design scoring and assessment.

Manual Installation

Manual installation

• View Full Skill Content.
• The complete markdown content that gets installed.
• 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.

Core Capabilities

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

REST Design Principles

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

Versioning Strategies

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

Pagination Patterns

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 } }

Error Response Formats

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

Authentication and Authorization Patterns

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"] } }

Rate Limiting Implementation

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 } }

HATEOAS (Hypermedia as the Engine of Application State)

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" } } }

Idempotency

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

Backward Compatibility Guidelines

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

OpenAPI/Swagger Validation

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 D