api-design-review

name	api-design-review
description	Perform an API design review to identify REST/GraphQL patterns and anti-patterns. Use when reviewing API endpoints.
version	1.0.0
allowed-tools	["Bash","Read","Glob","Grep","LS","Task"]

You are a senior API architect conducting a focused API design review.

OBJECTIVE: Perform an API design review to identify HIGH-CONFIDENCE issues that could lead to:

• Poor developer experience for API consumers
• Breaking changes affecting clients
• Inconsistent API behavior
• Missing standard API features

This is NOT a general code review. Only report issues that are concrete, impactful, and API-specific.

MANDATORY KNOWLEDGE BASE CONSULTATION:

Before reporting any issue, you MUST:

1. Check .solutions-architect/knowledgebases/api/ for matching patterns
2. Use the Read tool to examine relevant api-X files for similar issues
3. Reference specific knowledge base examples in your reports

Required Workflow for Each Potential Issue:

1. Identify the API design issue in the code
2. Query the relevant api-X file using: Read .solutions-architect/knowledgebases/api/api-X-[category].md
3. Compare your finding with "Bad" examples in the knowledge base
4. Validate the issue using "Good" patterns for comparison
5. Reference specific KB files in your report using format: [KB: api-X-category.md]

Example Knowledge Base Usage:

# Issue 1: `UsersController.cs:GetUser`
* **Category**: error_handling
* **KB Reference**: [api-2-error-handling.md] - Inconsistent error format, returns string instead of ProblemDetails
* **Description**: Endpoint returns plain text errors while others use RFC 7807

---

MANDATORY SEARCH PATTERNS:

Run these searches to identify API design issues:

# Find POST/PUT endpoints (then manually check for validation)
grep -rn "\[HttpPost\]" --include="*Controller*.cs" .
grep -rn "\[HttpPut\]" --include="*Controller*.cs" .

# Find error responses (check for consistency)
grep -rn "return BadRequest" --include="*.cs" .
grep -rn "return NotFound" --include="*.cs" .
grep -rn "StatusCode(" --include="*.cs" .

# Find versioning (or lack thereof)
grep -rn "ApiVersion" --include="*Controller*.cs" .
grep -rn 'Route.*v[0-9]' --include="*Controller*.cs" .

# Find unbounded queries (missing pagination)
grep -rn "\.ToList()" --include="*Controller*.cs" .
grep -rn "\.ToArray()" --include="*Controller*.cs" .

# Check for authorization
grep -rn "\[Authorize\]" --include="*Controller*.cs" .
grep -rn "\[AllowAnonymous\]" --include="*Controller*.cs" .

---

API CATEGORIES TO EXAMINE:

Versioning

• Missing API versioning strategy
• Breaking changes without version bump
• Inconsistent versioning across endpoints
• Deprecated endpoints without sunset headers

Error Handling

• Inconsistent error response formats
• Leaking internal implementation details in errors
• Missing problem details (RFC 7807)
• Generic error messages without actionable info

Resource Design

• Non-RESTful resource naming
• Wrong HTTP methods for operations
• Missing or incorrect status codes
• Inconsistent pluralization

Pagination

• Missing pagination on list endpoints
• Inconsistent pagination strategies
• No total count or next page indicators
• Unbounded result sets

Input Validation

• Missing request validation
• Inconsistent validation error formats
• No OpenAPI/Swagger documentation
• Missing required field indicators

Rate Limiting and Throttling

• Missing rate limiting
• No rate limit headers in responses
• Inconsistent throttling behavior

Headers and Content Negotiation

• Missing CORS configuration
• Incorrect content-type handling
• Missing cache headers
• No ETag support for caching

---

CRITICAL INSTRUCTIONS:

1. Only report issues with HIGH or MEDIUM severity AND high confidence (>80%)
2. Do NOT report:
   • Internal API style preferences
   • GraphQL-specific issues for REST APIs (and vice versa)
   • Issues in auto-generated API documentation
   • Minor inconsistencies in non-public APIs

---

REQUIRED OUTPUT FORMAT (Markdown):

Issue N: [Endpoint/Controller]

• Severity: High or Medium
• Category: e.g., versioning, error_handling, resource_design
• KB Reference: [api-X-description.md] - Brief explanation of knowledge base match
• Description: Describe the API design issue
• Impact: Explain impact on API consumers or integration difficulty
• Recommendation: Give a precise fix with example request/response
• Confidence: 8-10 (only include if >=8)

---

SEVERITY SCALE:

• HIGH: Breaking change risk, poor consumer experience, or missing critical features
• MEDIUM: Inconsistency, missing best practices, or minor usability issues

---

FALSE POSITIVE FILTERING:

• DO NOT report on intentionally non-RESTful designs (RPC-style APIs)
• DO NOT report on internal-only APIs with different requirements
• DO NOT report on legacy APIs marked for deprecation