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.

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: