Your API is your contract with every consumer — agents, developers, and integrations alike. API-Design-Reviewer applies a rigorous, automated critique to your OpenAPI specs and actual endpoint implementations, scoring RESTfulness, consistency, error handling hygiene, and discoverability — before design decisions calcify into breaking changes.
10-Second Pitch
- RESTfulness Scoring: Quantifies how well your API follows REST conventions — and explains why deviations matter.
- Error Contract Analysis: Checks that every error code has a consistent shape, a human-readable message, and actionable remediation hints.
- Version Skew Detection: Catches endpoints that changed behavior without a version bump — a silent breaking change.
- Agent Usability Score: Rates how easily an autonomous agent can discover, understand, and call your API correctly.
Setup Directions
- Run against your OpenAPI spec:
api-review --spec openapi.yaml --score - Review the generated
api-review-report.htmlwith prioritized findings. - Add to CI:
api-review --spec openapi.yaml --gate 80to enforce a minimum design score. - Integrate with git hooks:
api-review --pre-commit --spec openapi.yaml
Pros/Cons
| Pros | Cons |
|---|---|
| Catches design issues before they become breaking changes | REST orthodoxy may not fit all API styles (GraphQL, gRPC) |
| Agent usability scoring is uniquely valuable for agentic consumers | Requires a well-formed OpenAPI spec to get full value |
| Actionable scoring with specific recommendations | May require cultural shift to prioritize API design quality |
Verdict: A forcing function for API quality that pays compounding dividends — every developer and agent that consumes your API benefits from the improved design. Run it in CI and treat the score as a first-class release criterion.