api-design-reviewer_skill

Overview

This skill provides automated, production-ready reviews of REST API designs to improve consistency, security, and developer experience. It combines linting, breaking-change detection, and a multi-dimensional scorecard to surface actionable issues and recommendations. Use it to enforce conventions, catch regressions between spec versions, and track API quality over time.

How this skill works

The tool ingests OpenAPI/Swagger specifications and runs rule-based checks for naming, HTTP method usage, URL structure, status codes, error formats, authentication, pagination, and performance patterns. It compares two spec versions to detect breaking changes such as removed endpoints, field type changes, and new required fields. Finally, it produces a scored assessment across consistency, documentation, security, usability, and performance with detailed remediation guidance.

When to use it

• During API design reviews before implementation
• As part of CI/CD to enforce API quality gates
• When preparing a new API version or refactor to detect breaking changes
• Regular audits to maintain documentation and security hygiene
• Before public release or partner integration to ensure stability

Best practices

• Adopt consistent naming (kebab-case resources, camelCase fields) and HTTP semantics
• Version APIs explicitly (URL versioning recommended) and document migration paths
• Use standard error structures with requestId and timestamps for observability
• Implement pagination, caching, and field selection to optimize performance
• Validate OpenAPI specs with examples and reusable schemas to improve automation

Example use cases

• Run api_linter.py in CI to block commits with naming or documentation gaps
• Use breaking_change_detector.py to compare v1 and v2 specs and auto-generate migration notes
• Generate an API scorecard before launch to prioritize documentation and security fixes
• Add pre-commit hooks to enforce linting locally and prevent regressions
• Integrate api_scorecard.py into sprint retrospectives to track API quality improvements