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.

## Quick Start — run the tools first

```bash
# 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
```json
{
  "data": [...],
  "pagination": {
    "offset": 20,
    "limit": 10,
    "total": 150,
    "hasMore": true
  }
}
```

### Cursor-Based Pagination
```json
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIzfQ==",
    "hasMore": true
  }
}
```

### Page-Based Pagination
```json
{
  "data": [...],
  "pagination": {
    "page": 3,
    "pageSize": 10,
    "totalPages": 15,
    "totalItems": 150
  }
}
```

## Error Response Formats

### Standard Error Structure
```json
{
  "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, 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)
```json
{
  "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
```json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 3600
  }
}
```

## HATEOAS (Hypermedia as the Engine of Application State)

### Example Implementation
```json
{
  "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
- Define reusable components and schemas
- Validate against OpenAPI specification

## Performance Considerations

### 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)

## Security Best Practices

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

## Tools and Scripts

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

## Integration Examples

### CI/CD Integration
```yaml
- 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
```bash
#!/bin/bash
python engineering/skills/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

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

## Common Anti-Patterns to Avoid

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


Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle.

{
  "format": "aiskill/v1",
  "skill": {
    "name": "api-design-reviewer",
    "slug": "api-design-reviewer",
    "version": "1.0.0",
    "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.",
    "category": "Development",
    "tags": [
      "dev-workflow",
      "api"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# API Design Reviewer\r\n\r\n**Tier:** POWERFUL  \r\n**Category:** Engineering / Architecture  \r\n**Maintainer:** Claude Skills Team  \r\n\r\n## Overview\r\n\r\nThe 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.\r\n\r\n## Quick Start — run the tools first\r\n\r\n```bash\r\n# 1. Lint an OpenAPI/Swagger spec for convention violations\r\npython3 scripts/api_linter.py openapi.json --format json -o lint.json\r\n\r\n# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking)\r\npython3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json\r\n\r\n# 3. Score overall design quality (gate: --min-grade fails below threshold)\r\npython3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json\r\n```\r\n\r\nReview 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.\r\n\r\n## Core Capabilities\r\n\r\n### 1. API Linting and Convention Analysis\r\n- **Resource Naming Conventions**: Enforces kebab-case for resources, camelCase for fields\r\n- **HTTP Method Usage**: Validates proper use of GET, POST, PUT, PATCH, DELETE\r\n- **URL Structure**: Analyzes endpoint patterns for consistency and RESTful design\r\n- **Status Code Compliance**: Ensures appropriate HTTP status codes are used\r\n- **Error Response Formats**: Validates consistent error response structures\r\n- **Documentation Coverage**: Checks for missing descriptions and documentation gaps\r\n\r\n### 2. Breaking Change Detection\r\n- **Endpoint Removal**: Detects removed or deprecated endpoints\r\n- **Response Shape Changes**: Identifies modifications to response structures\r\n- **Field Removal**: Tracks removed or renamed fields in API responses\r\n- **Type Changes**: Catches field type modifications that could break clients\r\n- **Required Field Additions**: Flags new required fields that could break existing integrations\r\n- **Status Code Changes**: Detects changes to expected status codes\r\n\r\n### 3. API Design Scoring and Assessment\r\n- **Consistency Analysis** (30%): Evaluates naming conventions, response patterns, and structural consistency\r\n- **Documentation Quality** (20%): Assesses completeness and clarity of API documentation\r\n- **Security Implementation** (20%): Reviews authentication, authorization, and security headers\r\n- **Usability Design** (15%): Analyzes ease of use, discoverability, and developer experience\r\n- **Performance Patterns** (15%): Evaluates caching, pagination, and efficiency patterns\r\n\r\n## REST Design Principles\r\n\r\n### Resource Naming Conventions\r\n```\r\n✅ Good Examples:\r\n- /api/v1/users\r\n- /api/v1/user-profiles\r\n- /api/v1/orders/123/line-items\r\n\r\n❌ Bad Examples:\r\n- /api/v1/getUsers\r\n- /api/v1/user_profiles\r\n- /api/v1/orders/123/lineItems\r\n```\r\n\r\n### HTTP Method Usage\r\n- **GET**: Retrieve resources (safe, idempotent)\r\n- **POST**: Create new resources (not idempotent)\r\n- **PUT**: Replace entire resources (idempotent)\r\n- **PATCH**: Partial resource updates (not necessarily idempotent)\r\n- **DELETE**: Remove resources (idempotent)\r\n\r\n### URL Structure Best Practices\r\n```\r\nCollection Resources: /api/v1/users\r\nIndividual Resources: /api/v1/users/123\r\nNested Resources: /api/v1/users/123/orders\r\nActions: /api/v1/users/123/activate (POST)\r\nFiltering: /api/v1/users?status=active&role=admin\r\n```\r\n\r\n## Versioning Strategies\r\n\r\n### 1. URL Versioning (Recommended)\r\n```\r\n/api/v1/users\r\n/api/v2/users\r\n```\r\n**Pros**: Clear, explicit, easy to route  \r\n**Cons**: URL proliferation, caching complexity\r\n\r\n### 2. Header Versioning\r\n```\r\nGET /api/users\r\nAccept: application/vnd.api+json;version=1\r\n```\r\n**Pros**: Clean URLs, content negotiation  \r\n**Cons**: Less visible, harder to test manually\r\n\r\n### 3. Media Type Versioning\r\n```\r\nGET /api/users\r\nAccept: application/vnd.myapi.v1+json\r\n```\r\n**Pros**: RESTful, supports multiple representations  \r\n**Cons**: Complex, harder to implement\r\n\r\n### 4. Query Parameter Versioning\r\n```\r\n/api/users?version=1\r\n```\r\n**Pros**: Simple to implement  \r\n**Cons**: Not RESTful, can be ignored\r\n\r\n## Pagination Patterns\r\n\r\n### Offset-Based Pagination\r\n```json\r\n{\r\n  \"data\": [...],\r\n  \"pagination\": {\r\n    \"offset\": 20,\r\n    \"limit\": 10,\r\n    \"total\": 150,\r\n    \"hasMore\": true\r\n  }\r\n}\r\n```\r\n\r\n### Cursor-Based Pagination\r\n```json\r\n{\r\n  \"data\": [...],\r\n  \"pagination\": {\r\n    \"nextCursor\": \"eyJpZCI6MTIzfQ==\",\r\n    \"hasMore\": true\r\n  }\r\n}\r\n```\r\n\r\n### Page-Based Pagination\r\n```json\r\n{\r\n  \"data\": [...],\r\n  \"pagination\": {\r\n    \"page\": 3,\r\n    \"pageSize\": 10,\r\n    \"totalPages\": 15,\r\n    \"totalItems\": 150\r\n  }\r\n}\r\n```\r\n\r\n## Error Response Formats\r\n\r\n### Standard Error Structure\r\n```json\r\n{\r\n  \"error\": {\r\n    \"code\": \"VALIDATION_ERROR\",\r\n    \"message\": \"The request contains invalid parameters\",\r\n    \"details\": [\r\n      {\r\n        \"field\": \"email\",\r\n        \"code\": \"INVALID_FORMAT\",\r\n        \"message\": \"Email address is not valid\"\r\n      }\r\n    ],\r\n    \"requestId\": \"req-123456\",\r\n    \"timestamp\": \"2026-02-16T13:00:00Z\"\r\n  }\r\n}\r\n```\r\n\r\n### HTTP Status Code Usage\r\n- **400 Bad Request**: Invalid request syntax or parameters\r\n- **401 Unauthorized**: Authentication required\r\n- **403 Forbidden**: Access denied (authenticated but not authorized)\r\n- **404 Not Found**: Resource not found\r\n- **409 Conflict**: Resource conflict (duplicate, version mismatch)\r\n- **422 Unprocessable Entity**: Valid syntax but semantic errors\r\n- **429 Too Many Requests**: Rate limit exceeded\r\n- **500 Internal Server Error**: Unexpected server error\r\n\r\n## Authentication and Authorization Patterns\r\n\r\n### Bearer Token Authentication\r\n```\r\nAuthorization: Bearer <token>\r\n```\r\n\r\n### API Key Authentication\r\n```\r\nX-API-Key: <api-key>\r\nAuthorization: Api-Key <api-key>\r\n```\r\n\r\n### OAuth 2.0 Flow\r\n```\r\nAuthorization: Bearer <oauth-access-token>\r\n```\r\n\r\n### Role-Based Access Control (RBAC)\r\n```json\r\n{\r\n  \"user\": {\r\n    \"id\": \"123\",\r\n    \"roles\": [\"admin\", \"editor\"],\r\n    \"permissions\": [\"read:users\", \"write:orders\"]\r\n  }\r\n}\r\n```\r\n\r\n## Rate Limiting Implementation\r\n\r\n### Headers\r\n```\r\nX-RateLimit-Limit: 1000\r\nX-RateLimit-Remaining: 999\r\nX-RateLimit-Reset: 1640995200\r\n```\r\n\r\n### Response on Limit Exceeded\r\n```json\r\n{\r\n  \"error\": {\r\n    \"code\": \"RATE_LIMIT_EXCEEDED\",\r\n    \"message\": \"Too many requests\",\r\n    \"retryAfter\": 3600\r\n  }\r\n}\r\n```\r\n\r\n## HATEOAS (Hypermedia as the Engine of Application State)\r\n\r\n### Example Implementation\r\n```json\r\n{\r\n  \"id\": \"123\",\r\n  \"name\": \"John Doe\",\r\n  \"email\": \"john@example.com\",\r\n  \"_links\": {\r\n    \"self\": { \"href\": \"/api/v1/users/123\" },\r\n    \"orders\": { \"href\": \"/api/v1/users/123/orders\" },\r\n    \"profile\": { \"href\": \"/api/v1/users/123/profile\" },\r\n    \"deactivate\": { \r\n      \"href\": \"/api/v1/users/123/deactivate\",\r\n      \"method\": \"POST\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Idempotency\r\n\r\n### Idempotent Methods\r\n- **GET**: Always safe and idempotent\r\n- **PUT**: Should be idempotent (replace entire resource)\r\n- **DELETE**: Should be idempotent (same result)\r\n- **PATCH**: May or may not be idempotent\r\n\r\n### Idempotency Keys\r\n```\r\nPOST /api/v1/payments\r\nIdempotency-Key: 123e4567-e89b-12d3-a456-426614174000\r\n```\r\n\r\n## Backward Compatibility Guidelines\r\n\r\n### Safe Changes (Non-Breaking)\r\n- Adding optional fields to requests\r\n- Adding fields to responses\r\n- Adding new endpoints\r\n- Making required fields optional\r\n- Adding new enum values (with graceful handling)\r\n\r\n### Breaking Changes (Require Version Bump)\r\n- Removing fields from responses\r\n- Making optional fields required\r\n- Changing field types\r\n- Removing endpoints\r\n- Changing URL structures\r\n- Modifying error response formats\r\n\r\n## OpenAPI/Swagger Validation\r\n\r\n### Required Components\r\n- **API Information**: Title, description, version\r\n- **Server Information**: Base URLs and descriptions\r\n- **Path Definitions**: All endpoints with methods\r\n- **Parameter Definitions**: Query, path, header parameters\r\n- **Request/Response Schemas**: Complete data models\r\n- **Security Definitions**: Authentication schemes\r\n- **Error Responses**: Standard error formats\r\n\r\n### Best Practices\r\n- Use consistent naming conventions\r\n- Provide detailed descriptions for all components\r\n- Include examples for complex objects\r\n- Define reusable components and schemas\r\n- Validate against OpenAPI specification\r\n\r\n## Performance Considerations\r\n\r\n### Caching Strategies\r\n```\r\nCache-Control: public, max-age=3600\r\nETag: \"123456789\"\r\nLast-Modified: Wed, 21 Oct 2015 07:28:00 GMT\r\n```\r\n\r\n### Efficient Data Transfer\r\n- Use appropriate HTTP methods\r\n- Implement field selection (`?fields=id,name,email`)\r\n- Support compression (gzip)\r\n- Implement efficient pagination\r\n- Use ETags for conditional requests\r\n\r\n### Resource Optimization\r\n- Avoid N+1 queries\r\n- Implement batch operations\r\n- Use async processing for heavy operations\r\n- Support partial updates (PATCH)\r\n\r\n## Security Best Practices\r\n\r\n### Input Validation\r\n- Validate all input parameters\r\n- Sanitize user data\r\n- Use parameterized queries\r\n- Implement request size limits\r\n\r\n### Authentication Security\r\n- Use HTTPS everywhere\r\n- Implement secure token storage\r\n- Support token expiration and refresh\r\n- Use strong authentication mechanisms\r\n\r\n### Authorization Controls\r\n- Implement principle of least privilege\r\n- Use resource-based permissions\r\n- Support fine-grained access control\r\n- Audit access patterns\r\n\r\n## Tools and Scripts\r\n\r\n### api_linter.py\r\nAnalyzes API specifications for compliance with REST conventions and best practices.\r\n\r\n**Features:**\r\n- OpenAPI/Swagger spec validation\r\n- Naming convention checks\r\n- HTTP method usage validation\r\n- Error format consistency\r\n- Documentation completeness analysis\r\n\r\n### breaking_change_detector.py\r\nCompares API specification versions to identify breaking changes.\r\n\r\n**Features:**\r\n- Endpoint comparison\r\n- Schema change detection\r\n- Field removal/modification tracking\r\n- Migration guide generation\r\n- Impact severity assessment\r\n\r\n### api_scorecard.py\r\nProvides comprehensive scoring of API design quality.\r\n\r\n**Features:**\r\n- Multi-dimensional scoring\r\n- Detailed improvement recommendations\r\n- Letter grade assessment (A-F)\r\n- Benchmark comparisons\r\n- Progress tracking\r\n\r\n## Integration Examples\r\n\r\n### CI/CD Integration\r\n```yaml\r\n- name: \"api-linting\"\r\n  run: python scripts/api_linter.py openapi.json\r\n\r\n- name: \"breaking-change-detection\"\r\n  run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json\r\n\r\n- name: \"api-scorecard\"\r\n  run: python scripts/api_scorecard.py openapi.json\r\n```\r\n\r\n### Pre-commit Hooks\r\n```bash\r\n#!/bin/bash\r\npython engineering/skills/api-design-reviewer/scripts/api_linter.py api/openapi.json\r\nif [ $? -ne 0 ]; then\r\n  echo \"API linting failed. Please fix the issues before committing.\"\r\n  exit 1\r\nfi\r\n```\r\n\r\n## Best Practices Summary\r\n\r\n1. **Consistency First**: Maintain consistent naming, response formats, and patterns\r\n2. **Documentation**: Provide comprehensive, up-to-date API documentation\r\n3. **Versioning**: Plan for evolution with clear versioning strategies\r\n4. **Error Handling**: Implement consistent, informative error responses\r\n5. **Security**: Build security into every layer of the API\r\n6. **Performance**: Design for scale and efficiency from the start\r\n7. **Backward Compatibility**: Minimize breaking changes and provide migration paths\r\n8. **Testing**: Implement comprehensive testing including contract testing\r\n9. **Monitoring**: Add observability for API usage and performance\r\n10. **Developer Experience**: Prioritize ease of use and clear documentation\r\n\r\n## Common Anti-Patterns to Avoid\r\n\r\n1. **Verb-based URLs**: Use nouns for resources, not actions\r\n2. **Inconsistent Response Formats**: Maintain standard response structures\r\n3. **Over-nesting**: Avoid deeply nested resource hierarchies\r\n4. **Ignoring HTTP Status Codes**: Use appropriate status codes for different scenarios\r\n5. **Poor Error Messages**: Provide actionable, specific error information\r\n6. **Missing Pagination**: Always paginate list endpoints\r\n7. **No Versioning Strategy**: Plan for API evolution from day one\r\n8. **Exposing Internal Structure**: Design APIs for external consumption, not internal convenience\r\n9. **Missing Rate Limiting**: Protect your API from abuse and overload\r\n10. **Inadequate Testing**: Test all aspects including error cases and edge conditions\r\n\r\n\r\nRegular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle.",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The api-design-reviewer/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/api-design-reviewer",
    "exported_at": "2026-11-03T07:44:28.922Z"
  }
}

format: aiskill/v1
skill:
  name: api-design-reviewer
  slug: api-design-reviewer
  version: 1.0.0
  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.
  category: Development
  tags:
    - dev-workflow
    - api
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# API Design Reviewer\r\n\r\n**Tier:** POWERFUL  \r\n**Category:** Engineering / Architecture  \r\n**Maintainer:** Claude Skills Team  \r\n\r\n## Overview\r\n\r\nThe 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.\r\n\r\n## Quick Start — run the tools first\r\n\r\n```bash\r\n# 1. Lint an OpenAPI/Swagger spec for convention violations\r\npython3 scripts/api_linter.py openapi.json --format json -o lint.json\r\n\r\n# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking)\r\npython3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json\r\n\r\n# 3. Score overall design quality (gate: --min-grade fails below threshold)\r\npython3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json\r\n```\r\n\r\nReview 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.\r\n\r\n## Core Capabilities\r\n\r\n### 1. API Linting and Convention Analysis\r\n- **Resource Naming Conventions**: Enforces kebab-case for resources, camelCase for fields\r\n- **HTTP Method Usage**: Validates proper use of GET, POST, PUT, PATCH, DELETE\r\n- **URL Structure**: Analyzes endpoint patterns for consistency and RESTful design\r\n- **Status Code Compliance**: Ensures appropriate HTTP status codes are used\r\n- **Error Response Formats**: Validates consistent error response structures\r\n- **Documentation Coverage**: Checks for missing descriptions and documentation gaps\r\n\r\n### 2. Breaking Change Detection\r\n- **Endpoint Removal**: Detects removed or deprecated endpoints\r\n- **Response Shape Changes**: Identifies modifications to response structures\r\n- **Field Removal**: Tracks removed or renamed fields in API responses\r\n- **Type Changes**: Catches field type modifications that could break clients\r\n- **Required Field Additions**: Flags new required fields that could break existing integrations\r\n- **Status Code Changes**: Detects changes to expected status codes\r\n\r\n### 3. API Design Scoring and Assessment\r\n- **Consistency Analysis** (30%): Evaluates naming conventions, response patterns, and structural consistency\r\n- **Documentation Quality** (20%): Assesses completeness and clarity of API documentation\r\n- **Security Implementation** (20%): Reviews authentication, authorization, and security headers\r\n- **Usability Design** (15%): Analyzes ease of use, discoverability, and developer experience\r\n- **Performance Patterns** (15%): Evaluates caching, pagination, and efficiency patterns\r\n\r\n## REST Design Principles\r\n\r\n### Resource Naming Conventions\r\n```\r\n✅ Good Examples:\r\n- /api/v1/users\r\n- /api/v1/user-profiles\r\n- /api/v1/orders/123/line-items\r\n\r\n❌ Bad Examples:\r\n- /api/v1/getUsers\r\n- /api/v1/user_profiles\r\n- /api/v1/orders/123/lineItems\r\n```\r\n\r\n### HTTP Method Usage\r\n- **GET**: Retrieve resources (safe, idempotent)\r\n- **POST**: Create new resources (not idempotent)\r\n- **PUT**: Replace entire resources (idempotent)\r\n- **PATCH**: Partial resource updates (not necessarily idempotent)\r\n- **DELETE**: Remove resources (idempotent)\r\n\r\n### URL Structure Best Practices\r\n```\r\nCollection Resources: /api/v1/users\r\nIndividual Resources: /api/v1/users/123\r\nNested Resources: /api/v1/users/123/orders\r\nActions: /api/v1/users/123/activate (POST)\r\nFiltering: /api/v1/users?status=active&role=admin\r\n```\r\n\r\n## Versioning Strategies\r\n\r\n### 1. URL Versioning (Recommended)\r\n```\r\n/api/v1/users\r\n/api/v2/users\r\n```\r\n**Pros**: Clear, explicit, easy to route  \r\n**Cons**: URL proliferation, caching complexity\r\n\r\n### 2. Header Versioning\r\n```\r\nGET /api/users\r\nAccept: application/vnd.api+json;version=1\r\n```\r\n**Pros**: Clean URLs, content negotiation  \r\n**Cons**: Less visible, harder to test manually\r\n\r\n### 3. Media Type Versioning\r\n```\r\nGET /api/users\r\nAccept: application/vnd.myapi.v1+json\r\n```\r\n**Pros**: RESTful, supports multiple representations  \r\n**Cons**: Complex, harder to implement\r\n\r\n### 4. Query Parameter Versioning\r\n```\r\n/api/users?version=1\r\n```\r\n**Pros**: Simple to implement  \r\n**Cons**: Not RESTful, can be ignored\r\n\r\n## Pagination Patterns\r\n\r\n### Offset-Based Pagination\r\n```json\r\n{\r\n  \"data\": [...],\r\n  \"pagination\": {\r\n    \"offset\": 20,\r\n    \"limit\": 10,\r\n    \"total\": 150,\r\n    \"hasMore\": true\r\n  }\r\n}\r\n```\r\n\r\n### Cursor-Based Pagination\r\n```json\r\n{\r\n  \"data\": [...],\r\n  \"pagination\": {\r\n    \"nextCursor\": \"eyJpZCI6MTIzfQ==\",\r\n    \"hasMore\": true\r\n  }\r\n}\r\n```\r\n\r\n### Page-Based Pagination\r\n```json\r\n{\r\n  \"data\": [...],\r\n  \"pagination\": {\r\n    \"page\": 3,\r\n    \"pageSize\": 10,\r\n    \"totalPages\": 15,\r\n    \"totalItems\": 150\r\n  }\r\n}\r\n```\r\n\r\n## Error Response Formats\r\n\r\n### Standard Error Structure\r\n```json\r\n{\r\n  \"error\": {\r\n    \"code\": \"VALIDATION_ERROR\",\r\n    \"message\": \"The request contains invalid parameters\",\r\n    \"details\": [\r\n      {\r\n        \"field\": \"email\",\r\n        \"code\": \"INVALID_FORMAT\",\r\n        \"message\": \"Email address is not valid\"\r\n      }\r\n    ],\r\n    \"requestId\": \"req-123456\",\r\n    \"timestamp\": \"2026-02-16T13:00:00Z\"\r\n  }\r\n}\r\n```\r\n\r\n### HTTP Status Code Usage\r\n- **400 Bad Request**: Invalid request syntax or parameters\r\n- **401 Unauthorized**: Authentication required\r\n- **403 Forbidden**: Access denied (authenticated but not authorized)\r\n- **404 Not Found**: Resource not found\r\n- **409 Conflict**: Resource conflict (duplicate, version mismatch)\r\n- **422 Unprocessable Entity**: Valid syntax but semantic errors\r\n- **429 Too Many Requests**: Rate limit exceeded\r\n- **500 Internal Server Error**: Unexpected server error\r\n\r\n## Authentication and Authorization Patterns\r\n\r\n### Bearer Token Authentication\r\n```\r\nAuthorization: Bearer <token>\r\n```\r\n\r\n### API Key Authentication\r\n```\r\nX-API-Key: <api-key>\r\nAuthorization: Api-Key <api-key>\r\n```\r\n\r\n### OAuth 2.0 Flow\r\n```\r\nAuthorization: Bearer <oauth-access-token>\r\n```\r\n\r\n### Role-Based Access Control (RBAC)\r\n```json\r\n{\r\n  \"user\": {\r\n    \"id\": \"123\",\r\n    \"roles\": [\"admin\", \"editor\"],\r\n    \"permissions\": [\"read:users\", \"write:orders\"]\r\n  }\r\n}\r\n```\r\n\r\n## Rate Limiting Implementation\r\n\r\n### Headers\r\n```\r\nX-RateLimit-Limit: 1000\r\nX-RateLimit-Remaining: 999\r\nX-RateLimit-Reset: 1640995200\r\n```\r\n\r\n### Response on Limit Exceeded\r\n```json\r\n{\r\n  \"error\": {\r\n    \"code\": \"RATE_LIMIT_EXCEEDED\",\r\n    \"message\": \"Too many requests\",\r\n    \"retryAfter\": 3600\r\n  }\r\n}\r\n```\r\n\r\n## HATEOAS (Hypermedia as the Engine of Application State)\r\n\r\n### Example Implementation\r\n```json\r\n{\r\n  \"id\": \"123\",\r\n  \"name\": \"John Doe\",\r\n  \"email\": \"john@example.com\",\r\n  \"_links\": {\r\n    \"self\": { \"href\": \"/api/v1/users/123\" },\r\n    \"orders\": { \"href\": \"/api/v1/users/123/orders\" },\r\n    \"profile\": { \"href\": \"/api/v1/users/123/profile\" },\r\n    \"deactivate\": { \r\n      \"href\": \"/api/v1/users/123/deactivate\",\r\n      \"method\": \"POST\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Idempotency\r\n\r\n### Idempotent Methods\r\n- **GET**: Always safe and idempotent\r\n- **PUT**: Should be idempotent (replace entire resource)\r\n- **DELETE**: Should be idempotent (same result)\r\n- **PATCH**: May or may not be idempotent\r\n\r\n### Idempotency Keys\r\n```\r\nPOST /api/v1/payments\r\nIdempotency-Key: 123e4567-e89b-12d3-a456-426614174000\r\n```\r\n\r\n## Backward Compatibility Guidelines\r\n\r\n### Safe Changes (Non-Breaking)\r\n- Adding optional fields to requests\r\n- Adding fields to responses\r\n- Adding new endpoints\r\n- Making required fields optional\r\n- Adding new enum values (with graceful handling)\r\n\r\n### Breaking Changes (Require Version Bump)\r\n- Removing fields from responses\r\n- Making optional fields required\r\n- Changing field types\r\n- Removing endpoints\r\n- Changing URL structures\r\n- Modifying error response formats\r\n\r\n## OpenAPI/Swagger Validation\r\n\r\n### Required Components\r\n- **API Information**: Title, description, version\r\n- **Server Information**: Base URLs and descriptions\r\n- **Path Definitions**: All endpoints with methods\r\n- **Parameter Definitions**: Query, path, header parameters\r\n- **Request/Response Schemas**: Complete data models\r\n- **Security Definitions**: Authentication schemes\r\n- **Error Responses**: Standard error formats\r\n\r\n### Best Practices\r\n- Use consistent naming conventions\r\n- Provide detailed descriptions for all components\r\n- Include examples for complex objects\r\n- Define reusable components and schemas\r\n- Validate against OpenAPI specification\r\n\r\n## Performance Considerations\r\n\r\n### Caching Strategies\r\n```\r\nCache-Control: public, max-age=3600\r\nETag: \"123456789\"\r\nLast-Modified: Wed, 21 Oct 2015 07:28:00 GMT\r\n```\r\n\r\n### Efficient Data Transfer\r\n- Use appropriate HTTP methods\r\n- Implement field selection (`?fields=id,name,email`)\r\n- Support compression (gzip)\r\n- Implement efficient pagination\r\n- Use ETags for conditional requests\r\n\r\n### Resource Optimization\r\n- Avoid N+1 queries\r\n- Implement batch operations\r\n- Use async processing for heavy operations\r\n- Support partial updates (PATCH)\r\n\r\n## Security Best Practices\r\n\r\n### Input Validation\r\n- Validate all input parameters\r\n- Sanitize user data\r\n- Use parameterized queries\r\n- Implement request size limits\r\n\r\n### Authentication Security\r\n- Use HTTPS everywhere\r\n- Implement secure token storage\r\n- Support token expiration and refresh\r\n- Use strong authentication mechanisms\r\n\r\n### Authorization Controls\r\n- Implement principle of least privilege\r\n- Use resource-based permissions\r\n- Support fine-grained access control\r\n- Audit access patterns\r\n\r\n## Tools and Scripts\r\n\r\n### api_linter.py\r\nAnalyzes API specifications for compliance with REST conventions and best practices.\r\n\r\n**Features:**\r\n- OpenAPI/Swagger spec validation\r\n- Naming convention checks\r\n- HTTP method usage validation\r\n- Error format consistency\r\n- Documentation completeness analysis\r\n\r\n### breaking_change_detector.py\r\nCompares API specification versions to identify breaking changes.\r\n\r\n**Features:**\r\n- Endpoint comparison\r\n- Schema change detection\r\n- Field removal/modification tracking\r\n- Migration guide generation\r\n- Impact severity assessment\r\n\r\n### api_scorecard.py\r\nProvides comprehensive scoring of API design quality.\r\n\r\n**Features:**\r\n- Multi-dimensional scoring\r\n- Detailed improvement recommendations\r\n- Letter grade assessment (A-F)\r\n- Benchmark comparisons\r\n- Progress tracking\r\n\r\n## Integration Examples\r\n\r\n### CI/CD Integration\r\n```yaml\r\n- name: \"api-linting\"\r\n  run: python scripts/api_linter.py openapi.json\r\n\r\n- name: \"breaking-change-detection\"\r\n  run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json\r\n\r\n- name: \"api-scorecard\"\r\n  run: python scripts/api_scorecard.py openapi.json\r\n```\r\n\r\n### Pre-commit Hooks\r\n```bash\r\n#!/bin/bash\r\npython engineering/skills/api-design-reviewer/scripts/api_linter.py api/openapi.json\r\nif [ $? -ne 0 ]; then\r\n  echo \"API linting failed. Please fix the issues before committing.\"\r\n  exit 1\r\nfi\r\n```\r\n\r\n## Best Practices Summary\r\n\r\n1. **Consistency First**: Maintain consistent naming, response formats, and patterns\r\n2. **Documentation**: Provide comprehensive, up-to-date API documentation\r\n3. **Versioning**: Plan for evolution with clear versioning strategies\r\n4. **Error Handling**: Implement consistent, informative error responses\r\n5. **Security**: Build security into every layer of the API\r\n6. **Performance**: Design for scale and efficiency from the start\r\n7. **Backward Compatibility**: Minimize breaking changes and provide migration paths\r\n8. **Testing**: Implement comprehensive testing including contract testing\r\n9. **Monitoring**: Add observability for API usage and performance\r\n10. **Developer Experience**: Prioritize ease of use and clear documentation\r\n\r\n## Common Anti-Patterns to Avoid\r\n\r\n1. **Verb-based URLs**: Use nouns for resources, not actions\r\n2. **Inconsistent Response Formats**: Maintain standard response structures\r\n3. **Over-nesting**: Avoid deeply nested resource hierarchies\r\n4. **Ignoring HTTP Status Codes**: Use appropriate status codes for different scenarios\r\n5. **Poor Error Messages**: Provide actionable, specific error information\r\n6. **Missing Pagination**: Always paginate list endpoints\r\n7. **No Versioning Strategy**: Plan for API evolution from day one\r\n8. **Exposing Internal Structure**: Design APIs for external consumption, not internal convenience\r\n9. **Missing Rate Limiting**: Protect your API from abuse and overload\r\n10. **Inadequate Testing**: Test all aspects including error cases and edge conditions\r\n\r\n\r\nRegular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle."
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The api-design-reviewer/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/api-design-reviewer
  exported_at: "2026-11-03T07:44:28.922Z"