cloudthinker-ai 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:
- Design summary (API purpose, style, scope)
- Compliance scorecard (REST conventions, naming, consistency)
- Issues found by severity (blocking, major, minor)
- Recommendations (specific changes with examples)
- Approval status (APPROVED / REVISIONS NEEDED)