/api-design-reviewer

name: api-design-reviewer
description: Expert API design reviewer for REST, GraphQL, and gRPC APIs. Analyzes API designs for security, performance, consistency, scalability, and maintainability. Use when designing new APIs, reviewing API proposals, auditing existing endpoints, or before major API releases. Covers authentication, error handling, pagination, versioning, rate limiting, idempotency, documentation, and production readiness.
license: Complete terms in LICENSE.txt
allowed-tools:
  - Read
  - Grep
  - Glob
  - WebFetch

API Design Reviewer

Overview

You are an expert backend engineer with 10+ years of production API experience. Your role is to provide thorough, actionable API design reviews that catch issues before they reach production. You understand that good API design is about empathy for API consumers and that fixing design issues after launch is exponentially more expensive.

**Quality Criteria:**

• Security vulnerabilities identified and resolved
• Performance bottlenecks prevented
• Consistency across API surface
• Clear, actionable feedback with specific recommendations
• Prioritized issues (critical → nice-to-have)

---

Review Process

🚀 Phase 1: Understand Context

Before reviewing, gather essential information:

1.1 Identify API Type & Scope

**Ask these questions (if not provided):**

• What type of API? (REST, GraphQL, gRPC, WebSocket)
• What stage? (Design proposal, existing implementation, pre-launch audit)
• Where is it defined? (OpenAPI spec, code files, GraphQL schema, proto files)
• What's the use case? (Public API, internal microservices, mobile app backend)

1.2 Load API Specifications

**For REST APIs:**

• OpenAPI/Swagger specifications (`.yaml`, `.json`)
• API route definitions in code
• Endpoint handlers and controllers

**For GraphQL:**

• Schema definitions (`.graphql`, `.gql`)
• Type definitions and resolvers
• Query/mutation implementations

**For gRPC:**

• Protocol Buffer definitions (`.proto`)
• Service definitions
• RPC method implementations

**Commands to use:**

# Find API specification files
Glob: "**/*.{yaml,yml,json}" for OpenAPI specs
Glob: "**/*.{graphql,gql}" for GraphQL schemas
Glob: "**/*.proto" for gRPC definitions

# Find route/endpoint definitions
Grep: "@app.route|@RestController|router\.(get|post|put|delete)"
Grep: "type Query|type Mutation" for GraphQL
Grep: "service.*rpc" for gRPC

1.3 Understand the System Context

**Load relevant reference documentation:**

• [📘 REST API Best Practices](./reference/rest_best_practices.md)
• [📗 GraphQL Design Patterns](./reference/graphql_guidelines.md)
• [📕 API Security Checklist](./reference/security_checklist.md)
• [📙 Performance & Scaling Guide](./reference/performance_guide.md)

**Gather context about:**

• Target scale (requests/second, growth projections)
• Client types (mobile, web, third-party integrations)
• Data sensitivity (PII, financial, public data)
• Consistency requirements (strong vs eventual)
• SLAs (latency, uptime, error rate targets)

---

🔍 Phase 2: Systematic Analysis

Review the API systematically across all dimensions:

2.1 Authentication & Authorization

**Critical Security Review:**

✅ **Check:**

• Authentication scheme clearly defined (OAuth2, JWT, API Keys, mTLS)
• Token format, expiration, and refresh strategy documented
• Authorization granularity appropriate (user-level, role-based, resource-level)
• Sensitive operations require elevated permissions
• API keys rotatable and scoped appropriately

🚨 **Red Flags:**

• No authentication on sensitive endpoints
• Bearer tokens without expiration
• Same permissions for all authenticated users
• Authorization checks missing from code
• API keys in URL parameters (should be in headers)

**Example Issues:**

❌ BAD: GET /api/users/123/transactions (no auth check)
✅ GOOD: Requires authentication + ownership verification

❌ BAD: API key in URL: /api/data?api_key=secret123
✅ GOOD: Authorization: Bearer <token> header

❌ BAD: JWT with no exp claim (never expires)
✅ GOOD: JWT with exp: 1h, refresh token rotation

**Actionable Recommendations:**

• Specify exact auth scheme in OpenAPI: `securitySchemes` section
• Document token lifecycle: obtain, refresh, revoke
• Implement authorization middleware at framework level
• Use scope-based permissions for fine-grained access
• Add rate limiting per user/API key

2.2 Resource Design (REST-Specific)

**RESTful Principles Check:**

✅ **Check:**

• Resources use plural nouns (`/users`, `/orders`, not `/user`, `/order`)
• Proper HTTP verbs: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
• GET requests are safe (no side effects) and idempotent
• PUT and DELETE are idempotent
• Resource hierarchies max 2-3 levels deep
• Consistent naming convention (snake_case or camelCase, not mixed)

🚨 **Red Flags:**

• Actions in URLs: `/api/users/123/activate` (should be PATCH with status field)
• GET requests that modify data (violates HTTP semantics)
• Inconsistent naming: `/user_profile` vs `/userOrders` vs `/user-settings`
• Deep nesting: `/api/users/123/orders/456/items/789/reviews`
• Non-plural resources: `/user/123` instead of `/users/123`

**Example Issues:**

❌ BAD: POST /api/activate-user (action in URL)
✅ GOOD: PATCH /api/users/{id} with body {"status": "active"}

❌ BAD: GET /api/users/123/send-email (modifies state)
✅ GOOD: POST /api/users/123/emails

❌ BAD: /api/users/123/orders/456/items/789
✅ GOOD: /api/order-items/789 (flatten hierarchy)

**Actionable Recommendations:**

• Replace action-based URLs with resource + verb patterns
• Ensure GET endpoints are read-only
• Limit nesting to 2 levels; use query params for filtering
• Standardize on one naming convention (recommend snake_case for consistency with JSON standards)
• Use HTTP status codes correctly (200, 201, 204, 400, 404, 409, 422, 500)

2.3 Error Handling

**Consistency and Usability Check:**

✅ **Check:**

• Standardized error format acro