API Review Workflow

Evaluate API surfaces against guidelines and high-quality exemplars.

Quick Start

/api-review

When to Use

• Reviewing public API changes
• Designing new API surfaces
• Auditing API consistency
• Validating documentation completeness
• Before API releases

Required TodoWrite Items

1. api-review:surface-inventory
2. api-review:exemplar-research
3. api-review:consistency-audit
4. api-review:docs-governance
5. api-review:evidence-log

Workflow

Step 1: Surface Inventory

Module: @modules/surface-inventory.md

Detect and catalog all public APIs by language. Record stability levels, feature flags, and versioning metadata.

Quick commands:

pwd && git status -sb
rg -n "^pub" src  # Rust
rg -n "^def [^_]" package  # Python

Step 2: Exemplar Research

Module: @modules/exemplar-research.md

Find 2+ high-quality API references per language. Document patterns for namespacing, pagination, error handling, and documentation structure.

Common exemplars: pandas, requests, tokio, net/http, Stripe API

Step 3: Consistency Audit

Module: @modules/consistency-audit.md

Compare project API against exemplar patterns. Check naming, parameters, return types, error semantics, and deprecation handling.

Identify duplication, leaky abstractions, missing feature gates, and documentation gaps.

Step 4: Documentation Governance

Ensure documentation includes:

• Entry points and quickstarts
• Complete API reference
• Changelogs and migration notes
• Automated generation (rustdoc, Sphinx, typedoc, OpenAPI)

Verify versioning:

• SemVer compliance
• Stability promises
• Deprecation timelines

Step 5: Evidence Log

Dependency: imbue:evidence-logging

Record all executed commands and findings. Summarize recommendation (Approve / Approve with actions / Block) with action items, owners, and dates.

Progressive Loading

Load modules as needed:

• Always load: surface-inventory, consistency-audit
• Load for new designs: exemplar-research
• Load for documentation audits: Include docs-governance checklist

API Quality Checklist

Naming

• Consistent convention, clear descriptive names, follows language idioms

Parameters

• Consistent ordering, optional parameters have defaults, complete type annotations

Return Values

• Consistent patterns, error cases documented, pagination consistent

Documentation

• All public APIs documented with examples, changelog maintained

Output Format

## API Review Report

### Summary
[Assessment of API surface]

### Surface Inventory
- Endpoints/Functions: N
- Public types: N
- Stability: [stable/beta/experimental counts]

### Exemplar Comparison
[Key patterns from exemplars and alignment analysis]

### Consistency Issues
[I1] [Issue title]
- Location: file:line
- Recommendation: [fix]

### Documentation Gaps
[Identified gaps and required additions]

### Recommendations
- Decision: Approve / Approve with actions / Block
- Action items with owners and dates

Integration Notes

• Use imbue:evidence-logging for reproducible command capture
• Reference imbue:diff-analysis/modules/risk-assessment-framework for breaking change assessment
• Format output using imbue:structured-output for consistent findings

Exit Criteria

• Surface inventory complete with stability metadata
• Exemplars researched with pattern citations
• Consistency issues documented with locations
• Documentation gaps identified
• Action plan with ownership and timeline