api-design-review

name	api-design-review
enabled	true
description	Use when performing api design review — structured review template for evaluating API designs before implementation. Covers RESTful conventions, naming consistency, error handling patterns, pagination strategy, versioning, security considerations, and documentation completeness to ensure APIs are intuitive and maintainable.
required_connections	[{"prefix":"github","label":"GitHub"}]
config_fields	[{"key":"api_name","label":"API Name","required":true,"placeholder":"e.g., Customer Management API"},{"key":"api_spec_url","label":"API Spec URL or Path","required":true,"placeholder":"e.g., docs/openapi/customers.yaml"},{"key":"api_style","label":"API Style","required":false,"placeholder":"e.g., REST, GraphQL, gRPC"}]
features	["ENGINEERING","API_MANAGEMENT"]

API Design Review Skill

Review the design of {{ api_name }} ({{ api_style }}) from spec at {{ api_spec_url }}.

Workflow

Phase 1 — API Overview Assessment

API SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] API purpose and domain clearly defined
[ ] Target consumers identified:
    - Internal services: ___
    - External partners: ___
    - Public developers: ___
[ ] Endpoints/operations count: ___
[ ] Resources/entities modeled: ___
[ ] API style: {{ api_style }}

Phase 2 — Resource Design

RESOURCE MODELING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Resources represent domain nouns (not verbs)
[ ] Resource naming is consistent:
    [ ] Plural nouns for collections
    [ ] Lowercase with hyphens
    [ ] No unnecessary nesting (max 2 levels)
[ ] Resource relationships clearly expressed
[ ] Sub-resources vs. independent resources appropriate
[ ] Resource identifiers are opaque and stable

NAMING CONSISTENCY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Convention      | Consistent | Issues
Field casing    | [ ]        | ___
Date formats    | [ ]        | ___
Enum values     | [ ]        | ___
ID field naming | [ ]        | ___

Phase 3 — Operations Review

HTTP METHODS / OPERATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] GET for reads (no side effects)
[ ] POST for creation (returns 201)
[ ] PUT/PATCH for updates (PUT full, PATCH partial)
[ ] DELETE for removal (idempotent)
[ ] No state changes via GET
[ ] Idempotency considered for POST operations
[ ] Bulk operations provided where needed

STATUS CODES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] 200/201/204 used correctly for success
[ ] 400 for client validation errors
[ ] 401 for authentication failures
[ ] 403 for authorization failures
[ ] 404 for not found
[ ] 409 for conflicts
[ ] 429 for rate limiting
[ ] 500 reserved for unexpected server errors

Phase 4 — Error Handling

ERROR RESPONSE FORMAT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Consistent error response structure defined
[ ] Error responses include:
    [ ] Machine-readable error code
    [ ] Human-readable message
    [ ] Field-level validation details
    [ ] Request correlation ID
[ ] Error codes are documented and stable
[ ] No sensitive information leaked in errors
[ ] Validation errors return all failures (not just first)

Phase 5 — Pagination, Filtering, and Sorting

COLLECTION HANDLING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Pagination implemented for all list endpoints:
    [ ] Cursor-based (preferred for large datasets)
    [ ] Offset-based (simpler, acceptable for small sets)
[ ] Default and maximum page sizes defined
[ ] Filtering parameters are consistent
[ ] Sorting parameters are consistent
[ ] Total count available (or indicated if unavailable)
[ ] Link headers or next/prev cursors provided

Phase 6 — Security Review

SECURITY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Authentication method defined (OAuth2, API key, JWT)
[ ] Authorization model documented (RBAC, ABAC, scopes)
[ ] Rate limiting strategy defined
[ ] Input validation rules specified
[ ] Sensitive fields identified and handled:
    [ ] PII fields masked in logs
    [ ] Sensitive fields excluded from list responses
[ ] CORS policy appropriate for consumers
[ ] HTTPS enforced

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

Produce an API design review report with:

1. Design summary (API purpose, style, scope)
2. Compliance scorecard (REST conventions, naming, consistency)
3. Issues found by severity (blocking, major, minor)
4. Recommendations (specific changes with examples)
5. Approval status (APPROVED / REVISIONS NEEDED)