/api-design-reviewer

name: "api-design-reviewer"
description: "Comprehensive REST API design review with automated linting, breaking-change detection, and design scorecards. Catches inconsistent conventions, missing versioning, and design smells before APIs ship. Use when reviewing a PR that adds or changes API endpoints, auditing an existing API for v2 migration, or establishing API standards for a team."

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.

Quick Start — run the tools first

# 1. Lint an OpenAPI/Swagger spec for convention violations
python3 scripts/api_linter.py openapi.json --format json -o lint.json

# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking)
python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json

# 3. Score overall design quality (gate: --min-grade fails below threshold)
python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json

Review flow: run all three, report linter findings + breaking changes + grade to the user, fix, then re-run until the linter is clean, `--exit-on-breaking` passes (or breaking changes are version-bumped), and the scorecard meets the agreed `--min-grade`. Never sign off an API review on prose alone — attach the tool outputs.

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": "2026-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, versio