api-reviewing

Reviewing Existing APIs

Two review modes:

• HTTP/REST service — full checklist below
• Plugin skill inventory — use the plugin checklist at the end of this skill; same subdomain triage, different checklist

Step 0 — Subdomain triage

Calibrate review effort before applying the full checklist:

• Core subdomain (competitive advantage, frequently changing) → apply full checklist rigorously; no shortcuts
• Supporting subdomain (internal tooling, stable) → minimal checklist; shortcuts acceptable
• Generic subdomain (solved problem, provider may change) → focus on securitySchemes and contract strength; verify the boundary encapsulates provider details

Severity guide

Checklist section	Default severity	Rationale
Module boundary health	FAIL	Boundary violations compound — fix before merge
Spec quality	FAIL	Contract errors mislead all consumers
Agent-friendliness	FAIL for hard rules (x-agent-*, format: date-time, conflicting_id); WARN for documentation gaps (intent table, token lifecycle)	Hard rules are testable; documentation gaps are fixable post-merge
Design quality	FAIL for 422 misuse, missing idempotency; WARN for missing consistency model
Versioning hygiene	FAIL for breaking changes in minor; WARN for missing Sunset header
Testing coverage	WARN (blocking only if spec drift tests are entirely absent)

Override with judgment: a WARN in a core subdomain may warrant FAIL treatment.

HTTP/REST review checklist

Module boundary health

• Endpoints are business actions, not DB row operations
• No endpoints expose another module's internal schema
• No cross-domain endpoints (e.g., auth-service owning /projects/{id} — that belongs in project-service)
• Data ownership respected — no cross-module DB access visible
• Deep-module check: more than 4 fine-grained CRUD endpoints on the same resource = likely leaky boundary

Spec quality

• Every endpoint has operationId (camelCase verb+noun)
• All 4xx/5xx responses reference the Error component
• Error codes come from the recommended taxonomy (see api-first:api-design)
• Error component has: code, detail, correlation ID — consistent naming across all services
• Correlation ID on success responses too (not just errors)
• All list endpoints use {"items", "total", "offset", "limit"} envelope; empty state returns full envelope, never null
• Auth declared in securitySchemes; all routes require auth except observability + authentication endpoints
• info.version follows full semver (1.2.0, not 1.2)
• /openapi.json exposed without auth (capability discovery)

Agent-friendliness

• Every POST has x-agent-retryable set
• Every operation has x-agent-timeout set
• x-agent-idempotency header name set on operations supporting Idempotency-Key
• 401 responses use TOKEN_EXPIRED vs TOKEN_INVALID (vs TOKEN_REVOKED, INSUFFICIENT_SCOPE) error codes
• 409 responses include conflicting_id (or equivalent)
• All timestamp fields use format: date-time
• Null/absent convention documented and consistent across all services
• docs/agent-integration.md has intent→endpoint table and token lifecycle section

Design quality

• 422 used for business logic failures (not 400)
• Every POST documents its idempotency strategy
• PATCH endpoints use application/merge-patch+json and return the full resource
• Filter/sort parameters documented in operation parameters with defaults stated
• detail messages are actionable — consumer can fix without reading source code
• Consistency model documented on state-changing endpoints if non-obvious

Versioning hygiene

• No breaking changes in minor version history (check git log -- api/)
• Deprecated operations have deprecated: true + Sunset header
• v0 endpoints marked experimental in info.description

Testing coverage

• Spec drift tests exist (tests/test_openapi.py) including x-agent-* and format: date-time checks
• Schemathesis configured with exclusions documented in docstrings
• test_agent_friendliness.py exists (idempotency, token codes, pagination accuracy, 429 header)
• test_generated_spec.py exists for services with framework-generated specs (FastAPI, Flask-RESTX, DRF)
• CI runs oasdiff on every PR

Review output format (HTTP)

## API Review: {service}

### Subdomain: {core | supporting | generic} — {brief justification}

### Summary
- X failures (blocking)
- Y warnings (should fix)
- Z info findings

### Failures
- [FAIL] {path} {method}: {issue}. Fix: {actionable fix}

### Warnings
- [WARN] {path} {method}: {issue}. Suggestion: {suggestion}

### Module boundary findings
- [INFO] {observation}

Plugin skill inventory checklist

Skill interface quality

• Every SKILL.md has name and description in frontmatter
• description follows "Use when [specific conditions]" format — a trigger phrase, not a summary
• All cross-skill references use plugin-name:skill-name format (no bare paths)
• REQUIRED SUB-SKILL: and SOFT REFERENCE: markers used consistently

Agent-friendliness (skill content)

• Skill body uses tables, decision trees, and explicit "when X, do Y" rules — not prose walls
• No hedging language ("usually", "generally", "consider", "might") in normative sections
• Every rule has a clear scope: either a bounded exception list or no exceptions
• Code blocks for all executable content with expected output
• "Red flags" and "Anti-patterns" sections present (for discipline-enforcing skills)
• No "see also X" without explaining what X contributes

Versioning hygiene

• No skill renames or removals without a major version bump in plugin.json
• No description changes that alter when the skill fires without a major version bump
• plugin.json version field follows semver and is current

Plugin manifest

• plugin.json has name, version, skills path (Claude Code/Cursor)
• package.json has main pointing to OpenCode loader (if OpenCode supported)
• Hooks output correct JSON format for each target platform

Plugin review output format

## Plugin Review: {plugin-name}

### Subdomain: {core | supporting | generic} — {brief justification}

### Summary
- X failures (blocking)
- Y warnings (should fix)

### Failures
- [FAIL] {skill-name}: {issue}. Fix: {actionable fix}

### Warnings
- [WARN] {skill-name}: {issue}. Suggestion: {suggestion}

Cross-references

• REQUIRED SUB-SKILL: api-first:api-design (HTTP mode)
• REQUIRED SUB-SKILL: api-first:api-versioning
• REQUIRED SUB-SKILL: api-first:module-boundaries
• See api-first-workflow/references/plugin-tooling.md (plugin mode)
• SOFT REFERENCE: modularity:review — deeper coupling analysis across the full codebase

Note: This skill defines the review process. A future api-spec-reviewer agent (v1.2) will apply it to a specific spec file automatically.