API Review Command

Review an API design for best practices, consistency, and potential issues.

Usage

/sd:api-review [spec-file-or-pattern]

Arguments

• spec-file-or-pattern (optional): Path to OpenAPI spec, API file, or glob pattern
  • If provided: Review the specified file(s)
  • If omitted: Search for common API spec files (openapi.yaml, swagger.json, etc.)

Examples

/sd:api-review openapi.yaml
/sd:api-review src/api/**/*.ts
/sd:api-review

Workflow

1. Locate API Definitions

   • If spec file provided, read it
   • Otherwise, search for: openapi.yaml, openapi.json, swagger.yaml, swagger.json, *.graphql, *.proto
   • Also look for route/endpoint definitions in code

2. Spawn API Reviewer Agent Use the api-reviewer agent to analyze the API design. The agent will:

   • Identify the API type (REST, GraphQL, gRPC)
   • Apply best practices from loaded skills
   • Generate a structured review report

3. Present Findings Display the review organized by:

   • Critical issues (must fix)
   • Warnings (should address)
   • Suggestions (nice to have)
   • Positive observations

What Gets Reviewed

REST APIs

• Resource naming and URL structure
• HTTP method usage
• Status codes
• Error response format
• Pagination patterns

GraphQL APIs

• Schema design
• Query complexity
• N+1 prevention
• Error handling

gRPC APIs

• Message design
• Service patterns
• Backward compatibility

Cross-Cutting

• Versioning strategy
• Rate limiting
• Idempotency
• Security patterns
• Documentation quality

Output

The command produces a structured review report with:

• Summary of the API and overall assessment
• Issues categorized by severity
• Specific recommendations with examples
• Positive patterns to reinforce