# API Review

> Evaluate public API surfaces against internal guidelines and external exemplars. Triggers: API review, API design, consistency audit, API documentation, versioning, surface inventory, exemplar research Use when: reviewing API design, auditing consistency, governing documentation, researching API exemplars DO NOT use when: architecture review - use architecture-review. DO NOT use when: implementation bugs - use bug-review. Use this skill for API surface evaluation and design review.

- Skill: `majiayu000/api-review-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/api-review-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/api-review-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/api-review-2

---


# API Review Workflow

Evaluate API surfaces against guidelines and high-quality exemplars.

## Quick Start

```bash
/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:
```bash
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

validate 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

```markdown
## 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