Skill

api-design-review

Reviews public interfaces for API design quality including naming, method signatures, parameters, type safety, and REST endpoints. Use when evaluating usability and readability of class APIs or endpoints.

api-development

code-quality

npx claudepluginhub andonimichael/arxitect --plugin arxitect

Tool Access

This skill uses the workspace's default tool permissions.

Preview

You are performing an API design review. Evaluate the code's public

Supporting Assets

agent-prompt.mdmethod-and-parameter-design.mdnaming-conventions.mdrest-endpoint-design.md

SKILL.md

Similar Skills

api-review

Reviews API designs for best practices, consistency, and issues in REST, GraphQL, gRPC, OpenAPI specs, or code files.

4 tools

systems-design

spine-review

Reviews API and backend code for REST conventions, auth, validation, error handling, pagination, rate limiting, and test coverage.

11 tools

tonone

api-design

Designs and reviews public APIs, exported function signatures, module boundaries, types/interfaces, and code contracts to make correct usage easy and incorrect usage hard.

1 file

Stats

Stars60

Forks11

Last CommitMar 25, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

API Design Review

You are performing an API design review. Evaluate the code's public interfaces — class APIs, method signatures, REST endpoints, and type definitions — for usability, clarity, and self-documentation.

Review Process

Identify the scope. Determine the files you are meant to review. Either the files specified, recently changed files, or the entire codebase.
Catalog public interfaces. Identify all public-facing surfaces: class methods, exported functions, REST endpoints, type definitions, and configuration interfaces. Do not review internal or private utilities.
Evaluate naming. Check all names (classes, methods, parameters, endpoints) against the naming conventions in naming-conventions.md.
Evaluate method and parameter design. Assess method signatures for clarity, parameter count, type safety, and self-documentation. See method-and-parameter-design.md.
Evaluate REST endpoints (if applicable). Check endpoint design against the REST best practices in rest-endpoint-design.md.
Produce structured output. Follow the review output format defined in skills/architect/review-output-format.md. Every finding must include a severity, the principle violated, affected files, and a specific recommendation.

Finding ID Convention

API Design findings use prefix API- followed by a three-digit number: API-001, API-002, etc.

Severity Guidelines

CRITICAL: A public interface name is misleading, a method signature makes incorrect usage easy, or an API violates established conventions in a way that will confuse consumers.
WARNING: Naming could be clearer, a parameter list is too long, types are weaker than they could be, or an endpoint deviates from REST conventions.
SUGGESTION: Minor naming polish, documentation improvements, or stylistic consistency that would enhance readability.

Pragmatism

API design serves the humans who will use the interface. Evaluate names and signatures from the perspective of a developer encountering the API for the first time:

Can they understand what a method does from its name alone?
Can they call it correctly without reading the implementation?
Will their IDE's autocomplete guide them toward correct usage?
Will they be surprised by the behavior?

The best API is one that requires no documentation because the names and types communicate everything.