Api Design Reviewer

Api Design Reviewer

# API Design Reviewer

Most API reviews happen during code review, when the implementation is already written. By then, fundamental design flaws — wrong resource modeling, inconsistent naming conventions, missing pagination, inadequate error formats, security blind spots — are expensive to fix. Teams waste cycles on bikeshedding naming conventions instead of catching real issues. Junior developers learn bad patterns because there is no automated guardrail. The result: fragile APIs that need v2 in six months, confused integrators, and security vulnerabilities that ship to production. This skill brings design review left — to the specification stage — so you catch structural problems before a single line of endpoint code is written.

What It Does

• Parses and analyzes OpenAPI 3.x and Swagger 2.0 specifications for REST API design quality
• Scores API designs across 8 quality dimensions: resource modeling, naming conventions, HTTP method usage, status code correctness, security posture, pagination strategy, error handling, and documentation completeness
• Supports REST (RESTful), GraphQL (schema SDL), and gRPC (protobuf) design review
• Generates severity-tagged review reports (Critical, Warning, Suggestion, Nitpick)
• Produces machine-readable JSON output for CI/CD pipeline integration
• Includes remediation steps for every finding

Frameworks and Standards Covered

| Standard | Type | Coverage | |---|---|---| | OpenAPI 3.0 / 3.1 | Specification | Full parsing, validation, scoring | | Swagger 2.0 | Specification | Full parsing, validation, scoring | | GraphQL Schema SDL | Specification | Endpoint naming, mutation structure, query analysis | | Protocol Buffers (proto3) | Specification | Service definition analysis | | RESTful Resource Modeling | Design Pattern | Resource naming, hierarchy depth, HTTP verb usage | | Zalando REST API Guidelines | Industry Standard | 50+ rule checks | | Microsoft REST API Guidelines | Industry Standard | 40+ rule checks | | Google API Design Guide | Industry Standard | Resource-oriented design patterns | | JSON:API Specification | Standard | Response format compliance | | OWASP API Security Top 10 | Security | 30+ security checks | | HTTP Status Code Standards (RFC 7231) | RFC | Correct code usage validation | | RFC 7807 Problem Details | RFC | Error response format validation |

Detailed Feature Breakdown

### 1. REST API Design Review The core engine analyzes OpenAPI/Swagger specifications for structural and stylistic quality. It walks every path, operation, parameter, and response to flag issues across: Resource Modeling: Detects verb-based endpoint names (`/getUsers` instead of `/users`), inconsistent pluralization (`/user` vs `/users`), improper nesting (3+ levels deep), and non-standard collection naming. HTTP Method Usage: Validates that GET operations are safe and idempotent, POST is used for creation only, PUT/PATCH semantics are correct (full vs partial replacement), and DELETE is idempotent. Flags GET endpoints with request bodies, POST endpoints used for queries, and methods used for unintended purposes. Status Codes: Checks that every operation defines expected responses. Flags missing 201 responses for POST, missing 204 for DELETE, use of 200 for creation, missing 4xx/5xx error responses, and inconsistent code usage across similar operations. Security Analysis: Scans for missing or inadequate security schemes (no auth defined, OAuth2 scopes missing, API keys used for sensitive operations). Flags examples containing hardcoded credentials, tokens, or API keys. Checks CORS configuration for overly permissive origins. Pagination: Detects collection endpoints (GET on array-type paths) that lack pagination parameters. Validates pagination is cursor-based for large datasets. Flags missing page size limits and missing `next`/`prev` link conventions. Error Handling: Validates that error responses follow a consistent schema across all paths. Checks for RFC 7807 Problem Details compliance. Flags endpoints that return 200 with error-in-body pattern (which breaks client error handling). Naming Conventions: Detects inconsistencies in parameter naming styles (mixing camelCase, snake_case, kebab_case), path segment casing, and query parameter naming across the entire spec. Documentation Completeness: Checks that every operation has a summary and description. Validates that every parameter has a description. Flags undocumented request body schemas and response schemas. ### 2. GraphQL Schema Review For GraphQL APIs, the skill analyzes schema SDL files: - Checks query/mutation naming follows consistent conventions (camelCase for fields, PascalCase for types) - Flags missing descriptions on types, fields, arguments, and enums - Detects over-fetching risk (types with 20+ fields that are always returned together) - Validates that mutations return a proper payload type (not just a scalar) - Checks for nullability best practices (non-null for IDs and required fields) - Detects naming collisions and confusing type names - Flags missing pagination on list-type queries ### 3. gRPC / protobuf Review For gRPC APIs defined in proto3: - Checks service naming consistency - Validates RPC method naming conventions - Flags missing comments on services, RPCs, and messages - Detects improper field numbering (skipping numbers, reserved ranges) - Checks for missing error handling patterns - Validates message naming conventions ### 4. Scoring and Report Generation Every review produces: - Overall Score: 0-100 quality score with letter grade (A-F) - Dimension Scores: Individual scores for each of the 8 quality dimensions - Severity-Tagged Findings: Each issue gets a severity: Critical, Warning, Suggestion, or Nitpick - Remediation Steps: Specific, actionable fix for every finding - Compliance Pass/Fail: Per-standard compliance indicators Output formats: Markdown (human-readable), JSON (machine-readable for CI/CD).

Usage

### Quick Start ```bash # Review an OpenAPI specification python3 scripts/cli.py review specification.yaml # Review with custom configuration python3 scripts/cli.py review specification.yaml --config config/rules.yaml --format json # Review GraphQL schema python3 scripts/cli.py review schema.graphql --type graphql # List all available rules python3 scripts/cli.py rules # Output report to file python3 scripts/cli.py review spec.yaml --output /path/to/report.md ``` ### Configuration Create a `config.yaml` file to customize review rules: ```yaml severity: default: warning security: critical naming: suggestion documentation: nitpick checks: resource_naming: true http_methods: true status_codes: true security: true pagination: true error_handling: true naming_consistency: true documentation: true standards: - zalando - microsoft - google min_score: 80 fail_on_critical: true ```

Output Format

### Example Report (Markdown) ``` # API Design Review: Pet Store API v3 Overall Score: 72/100 (C) Specification: petstore-v3.yaml Date: 2026-07-06

Dimension Scores

| Dimension | Score | Status | |---|---|---| | Resource Modeling | 85 | Good | | Naming Conventions | 65 | Warning | | HTTP Method Usage | 90 | Good | | Status Codes | 55 | Needs Work | | Security Posture | 40 | Critical | | Pagination | 30 | Critical | | Error Handling | 70 | Fair | | Documentation | 80 | Fair |

Findings

### CRITICAL (3) 1. Missing security scheme on /pets/{petId} - Path: /pets/{petId} GET - No authentication defined for this endpoint - Fix: Add security: [{ bearerAuth: [] }] to the operation 2. No pagination on collection endpoint /pets - Returns array without pagination parameters - Large datasets will cause performance issues - Fix: Add page/limit or cursor parameters 3. Example contains hardcoded API key - Path: /pets POST, in example value - 'api-key: sk-1234567890abcdef' - Fix: Use placeholder values like 'sk-xxxxxxxxxxxx' ### WARNING (7) [.. full report continues ..] ``` ### JSON Output (for CI/CD) ```json { "spec": "petstore-v3.yaml", "overall_score": 72, "grade": "C", "passed": false, "findings": [ { "severity": "critical", "rule": "missing-security", "path": "/pets/{petId} GET", "message": "No authentication defined", "remediation": "Add security scheme" } ], "dimensions": { "resource_modeling": 85, "naming": 65, "http_methods": 90, "status_codes": 55, "security": 40, "pagination": 30, "error_handling": 70, "documentation": 80 } } ```

Why This Beats Prompting It Yourself

AspectAd-Hoc PromptingThis Skill Manual Prompting This Skill --- --- --- Coverage 5-15 checks (what you remember) 80+ automated checks Consistency Varies per session Fixed, repeatable rules Standards General knowledge Zalando, Microsoft, Google, OWASP Speed 20-40 minutes per spec 2-5 seconds Severity grading Subjective Rule-based, consistent Remediation You write fixes Auto-generated steps CI/CD integration Not practical JSON output, exit codes Security checks Memory-dependent 30+ automated scans Depth Surface-level Structural, semantic, and spec compliance

Use Cases

• Pre-Implementation Gate: A team designs an API contract in OpenAPI. Before writing any code, they run the API Design Reviewer and fix the 15 issues it flags — saving a week of refactoring later.
• CI/CD Pipeline Gate: An engineering org requires every new API spec to score 80+ before merging. The CI pipeline runs the reviewer and blocks merges that introduce security gaps or naming inconsistencies.
• API Migration Audit: A company migrating from Swagger 2.0 to OpenAPI 3.1 runs the reviewer on their legacy specs to identify patterns that need updating and document current-state quality.
• Onboarding New Team Members: A new backend developer submits their first API proposal. The reviewer catches resource modeling errors and naming inconsistencies, providing automated teaching feedback.
• Third-Party API Evaluation: Before integrating a vendor API, a team runs the reviewer to assess the vendor's design quality, identify security concerns, and understand error handling patterns.