Api Review

API Review Workflow

Table of Contents

1. Usage 2. Required Progress Tracking 3. Workflow

Usage

Use this skill to review public API changes, design new surfaces, audit consistency, and validate documentation completeness. Run it before any API release to confirm alignment with project guidelines.

Required Progress Tracking

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 6. api-review:findings-verified

Workflow

Step 1: Surface Inventory

Catalog all public APIs by language. Record stability levels, feature flags, and versioning metadata. Use tools like rg to find public symbols (e.g., pub in Rust or non-underscored def in Python). Confirm the working tree state with git status before starting.

Step 2: Exemplar Research

Identify at least two high-quality API references for the relevant language, such as pandas, requests, or tokio. Document their patterns for namespacing, pagination, error handling, and structure to serve as a baseline for the audit.

Step 3: Consistency Audit

Compare the project's API against the identified exemplar patterns. Analyze naming conventions, parameter ordering, return types, and error semantics. Identify duplication, leaky abstractions, missing feature gates, and documentation gaps.

Step 4: Documentation Governance

Validate that documentation includes entry points, quickstarts, and a complete API reference. Verify that changelogs and migration notes are maintained. Check for SemVer compliance, stability promises, and clear deprecation timelines. Confirm that documentation is generated automatically using tools like rustdoc, Sphinx, or OpenAPI.

Step 5: Evidence Log

Record all executed commands and findings. Summarize the final recommendation as Approve, Approve with actions, or Block. Include specific action items with assigned owners and due dates.

API Quality Checklist

Naming

Confirm consistent conventions and descriptive names that follow language-specific idioms.

Parameters

Verify consistent ordering and ensure optional parameters have explicit defaults. Check that type annotations are complete.

Return Values

Analyze return patterns for consistency. Confirm that error cases are documented and that pagination follows a uniform structure.

Documentation

Verify that all public APIs include usage examples and that the changelog reflects current changes.

Output Format

The final report must include a summary of the API surface, a numerical inventory of endpoints and public types, and an alignment analysis against researched exemplars. Document consistency issues and documentation gaps with precise file and line references. Conclude with a clear decision and a timed action plan.

Each issue must follow this structure:

[A1] Title
- Location: file.py:42
- Anchor: `verbatim source text at line 42`
- Issue: what is wrong | Fix: remediation | Evidence: [E1]

The Anchor is the exact source text at Location; it is what citation_verifier.py re-reads to prove the finding is real.

Technical Integration

Use imbue:proof-of-work for reproducible command capture and imbue:structured-output for formatting findings. Reference imbue:diff-analysis/modules/risk-assessment-framework when assessing breaking changes.

Module Reference

• See modules/surface-inventory.md for API cataloging patterns
• See modules/exemplar-research.md for researching API standards
• See modules/consistency-audit.md for cross-API consistency checks

Verify Findings Are Grounded (api-review:findings-verified)

Every finding must cite a real location and a verbatim anchor. Write findings to .review/findings.json and confirm each citation resolves:

python plugins/imbue/scripts/citation_verifier.py \
  --findings .review/findings.json --repo-root .

Drop or label UNVERIFIED any finding the verifier fails (exit 1); only verified findings enter the report. See Skill(imbue:review-core) Step 5 and Skill(imbue:structured-output) for the schema.

Exit Criteria

• Surface inventoried, exemplars researched, consistency audited,

documentation governance checked, and evidence logged.

• Every reported finding carries a Location + verbatim Anchor

confirmed by citation_verifier.py (exit 0), or unverified findings were dropped or labeled UNVERIFIED.

Troubleshooting

If the audit command is missing, verify that dependencies are installed and accessible in the system PATH. Check file permissions if access errors occur. Use the --verbose flag to inspect execution logs if the tool behaves unexpectedly.

Consistency Audit

Compare API surfaces against exemplar patterns and internal consistency rules.

Naming Consistency

Check Patterns

• Verb/noun ordering: get_user vs user_get
• Pluralization: get_items vs get_item_list
• Abbreviations: cfg vs config, ctx vs context
• Case conventions: snake_case, camelCase, PascalCase

Commands

# Function name patterns
rg -n "^(pub )?fn " src | cut -d: -f2 | sort | uniq -c

# Type name patterns
rg -n "^(pub )?struct|enum|type" src

# HTTP endpoint patterns
rg -n "path.*=.*\"" src | grep -o '"[^"]*"' | sort

Red Flags

• Mixed naming conventions in same module
• Inconsistent verb prefixes (get vs fetch vs retrieve)
• Language idiom violations

Parameter Conventions

Check for Consistency

1. Ordering: receiver, required, optional, callbacks 2. Optional handling: Option types, defaults, overloads 3. Builder patterns: When to use vs direct construction 4. Type annotations: Complete and accurate

Language-Specific

Rust

// Consistent ordering: receiver, required, optional
impl Client {
    pub fn new(config: Config) -> Self { }
    pub fn with_timeout(mut self, timeout: Duration) -> Self { }
}

Python

# Consistent optional parameters
def read_data(path: str,
              format: str = "csv",
              encoding: str = "utf-8") -> DataFrame:
    pass

Go

// Consistent context placement
func GetUser(ctx context.Context, id string) (*User, error)

Audit Commands

# Parameter counts and patterns
rg -n "fn \w+\(" src | rg -o "\(.*\)" | sort | uniq -c

# Optional parameter patterns
rg -n "Option<|Optional<|\?:" src

Return Type Patterns

Consistency Checks

• Error handling: Result types, exceptions, error tuples
• Null handling: Option types, nullable annotations
• Collection returns: List, Array, Iterator
• Pagination: Page objects, cursor tokens

By Language

Rust

# Result usage
rg -n "-> Result<" src

# Option usage
rg -n "-> Option<" src

Python

# Type hints
rg -n "-> (List|Dict|Optional|Union)" package

# Exception documentation
rg -n "Raises:" docs

Go

# Error returns (should be last)
rg -n "func .* \(.*error\)$" .

# Pointer returns
rg -n "func .* \*\w+," .

Red Flags

• Mixed error handling strategies
• Inconsistent null/empty semantics
• Varying pagination approaches

Error Semantics

Check Consistency

1. Error types: Custom vs standard 2. Error messages: Format and detail level 3. Error codes: Numeric, string, or enum 4. Retry guidance: Transient vs permanent

Audit Pattern

# Custom error types
rg -n "struct \w*Error|enum \w*Error" src

# Error creation patterns
rg -n "Error::new|errors\.New|raise \w+Error" src

# HTTP status codes
rg -n "StatusCode::|status_code|status =" src

Expected Patterns

• Structured error hierarchy
• Consistent error construction
• Clear transient vs permanent distinction
• Actionable error messages

Deprecation Handling

Check for Proper Deprecation

1. Attributes/decorators: #[deprecated], @deprecated 2. Documentation: Clear migration path 3. Timeline: Version removal planned 4. Alternatives: Replacement API documented

Commands

# Deprecation markers
rg -n "#\[deprecated|@deprecated|DEPRECATED" src

# Migration notes
rg -n "migration|migrating|instead use" docs

Expected Pattern

#[deprecated(since = "1.2.0", note = "Use `new_api` instead")]
pub fn old_api() { }

Anti-Patterns

Detect Common Issues

Duplication

# Similar function names
rg -n "^(pub )?fn " src | cut -d: -f2 | sort | uniq -d

Leaky Abstractions

• Internal types in public signatures
• Implementation details exposed
• Platform-specific APIs without gates

Missing Feature Gates

# Check conditional compilation
rg -n "#\[cfg\(|#\[cfg_attr\(" src

Test Coverage Audit

Verify API Testing

# Test files covering public API
find tests -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  \( -name "test_*.py" -o -name "*_test.go" -o -name "*.test.ts" \)

# Integration tests
rg -n "integration|e2e|contract" tests

Expected Coverage

• Unit tests for each public function
• Integration tests for workflows
• Contract tests for external APIs
• Edge case coverage

Output Format

## Consistency Audit Results

### Naming Issues
- [I1] Mixed case conventions in module X
  - Location: file:line
  - Pattern: snake_case vs camelCase
  - Recommendation: Standardize on snake_case

### Parameter Issues
- [I2] Inconsistent optional parameter handling
  - Location: functions A, B, C
  - Pattern: Mixed Option<T> and default values
  - Recommendation: Use Option<T> consistently

### Return Type Issues
- [I3] Mixed error handling
  - Locations: file1.rs, file2.rs
  - Pattern: Some functions return Result, others panic
  - Recommendation: Consistent Result returns

### Deprecation Issues
- [I4] Missing migration path for deprecated API
  - Location: old_api()
  - Issue: No alternative documented
  - Recommendation: Document replacement

Exemplar Research

Identify and analyze high-quality API references to establish pattern baselines.

Language-Specific Exemplars

Python

pandas DataFrame API

• Namespace: pd.DataFrame.*
• Patterns: Method chaining, symmetric I/O (read_*/to_*)
• Documentation: Multi-level (quickstart, API reference, examples)
• URL: https://pandas.pydata.org/docs/reference/frame.html

requests Session API

• Namespace: requests.Session
• Patterns: Context managers, connection pooling
• Error handling: Structured exceptions hierarchy
• URL: https://requests.readthedocs.io/en/latest/api/

Rust

tokio Runtime API

• Namespace: tokio::runtime
• Patterns: Builder pattern, async traits
• Documentation: Module-level docs, examples
• URL: https://docs.rs/tokio/latest/tokio/runtime/

serde Serialization

• Namespace: serde::Serialize
• Patterns: Derive macros, trait composition
• Stability: Feature gates for optional formats
• URL: https://docs.rs/serde/latest/serde/

Go

net/http Package

• Namespace: net/http
• Patterns: Interface composition, handler chains
• Error handling: Explicit error returns
• URL: https://pkg.go.dev/net/http

database/sql

• Namespace: database/sql
• Patterns: Connection pooling, prepared statements
• Resource management: Explicit Close()
• URL: https://pkg.go.dev/database/sql

TypeScript

Express.js Router

• Namespace: express.Router
• Patterns: Middleware composition, fluent API
• Type safety: DefinitelyTyped integration
• URL: https://expressjs.com/en/4x/api.html

REST APIs

Stripe API

• Patterns: Nested resources, pagination, idempotency
• Versioning: Date-based with headers
• Documentation: Interactive examples
• URL: https://stripe.com/docs/api

GitHub REST API

• Patterns: HATEOAS links, rate limiting
• Pagination: Link headers, cursor-based
• Errors: Structured error responses
• URL: https://docs.github.com/en/rest

Pattern Capture

For Each Exemplar

Record: 1. Relevance: Why this exemplar applies 2. Key patterns: 2-3 standout design decisions 3. Documentation approach: Structure and tooling 4. Versioning strategy: How stability is managed

Common Patterns to Extract

Namespacing

• Flat vs hierarchical
• Module organization
• Import conventions

Pagination

• Cursor-based
• Offset-based
• Link headers
• Total count metadata

Error Handling

• Exception hierarchies
• Error codes/types
• Error response structure
• Retry guidance

Authentication

• API keys
• OAuth flows
• Token refresh
• Scope management

Citation Format

Store references:

## Exemplar: [Name]
**Language**: [Rust/Python/etc]
**URL**: [link]
**Relevance**: [why applicable]

### Key Patterns
1. [Pattern 1]: [description]
2. [Pattern 2]: [description]

### Applied to This Project
- [Comparison with current API]
- [Recommendations for alignment]

Research Workflow

1. Identify language/API type 2. Find 2-3 exemplars per category 3. Document patterns with citations 4. Compare with current project API 5. Note alignment and gaps

Surface Inventory

Catalog all public API surfaces, stability promises, and versioning metadata.

Detection by Language

Rust

# Public functions and types
rg -n "^pub" src

# Generate documentation
cargo doc --no-deps

# Check feature flags
rg -n "^#\[cfg\(feature" src

Python

# Public functions
rg -n "^def [^_]" package

# Exported items
rg -n "^__all__" package

# Sphinx documentation
sphinx-build -b html docs docs/_build

Go

# List packages
go list ./...

# Public functions
rg -n "^func [A-Z]"

# Generate docs
go doc -all

TypeScript

# Show configuration
tsc --showConfig

# Exported items
rg -n "^export" src

# Generate documentation
npx typedoc

HTTP/REST APIs

# Framework endpoints
rg -n "@app\.(get|post|put|delete)"

# OpenAPI spec
grep -n "path:" openapi.yaml
yq eval '.paths' openapi.yaml

Stability Metadata

Capture for Each API

• Stability level: stable, beta, alpha, experimental
• Version introduced: semver or date
• Deprecation status: deprecated, planned, stable
• Feature flags: compile-time, runtime, experimental

Commands by Language

# Rust: Stability attributes
rg -n "#\[(stable|unstable|deprecated)" src

# Python: Version metadata
rg -n "__version__|version_info" package

# Go: Build tags
rg -n "^// \+build" .

# OpenAPI: Version field
yq eval '.info.version' openapi.yaml

Output Structure

Record in evidence log:

## Surface Inventory

### Language: [Rust/Python/Go/etc]
- Public functions: N
- Public types: N
- Feature flags: N
- Stability: [table]

### Endpoints (HTTP)
- GET endpoints: N
- POST endpoints: N
- Version: v1, v2

### Stability Distribution
- Stable: N
- Beta: N
- Experimental: N

Versioning Patterns

SemVer (Rust, Node.js)

grep "^version" Cargo.toml
grep "\"version\"" package.json

CalVer (APIs)

yq eval '.info.version' openapi.yaml

Feature Versioning

# API version headers
rg -n "api-version|API-Version" src