borghei/Claude-Skills / engineering/api-design-reviewer
api-design-reviewer
VerifiedReview REST API designs for quality, consistency, and breaking changes. Lints OpenAPI specs, generates scorecards, and detects breaking changes between versions. Use when designing APIs, reviewing contracts, or managing API versioning.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| assets/sample_openapi_v1.json | config | 2.2 KB |
| assets/sample_openapi_v2.json | config | 3.2 KB |
| references/api_antipatterns.md | markdown | 13.4 KB |
| references/rest-design-patterns.md | markdown | 6.6 KB |
| references/rest_design_rules.md | markdown | 10.2 KB |
| references/tooling-ci-and-troubleshooting.md | markdown | 10.4 KB |
| scripts/api_linter.py | script | 37.4 KB |
| scripts/api_scorecard.py | script | 64.4 KB |
| scripts/breaking_change_detector.py | script | 47.9 KB |
references/tooling-ci-and-troubleshooting.md
View on GitHub# Tooling, CI Integration, Best Practices, Troubleshooting & Tool Reference
Read this when wiring the tools into CI/pre-commit, applying the best-practice/anti-pattern checklists, troubleshooting, or needing full CLI flag references.
## Tools and Scripts
### api_linter.py
Analyzes API specifications for compliance with REST conventions and best practices.
**Features:**
- OpenAPI/Swagger spec validation
- Naming convention checks
- HTTP method usage validation
- Error format consistency
- Documentation completeness analysis
### breaking_change_detector.py
Compares API specification versions to identify breaking changes.
**Features:**
- Endpoint comparison
- Schema change detection
- Field removal/modification tracking
- Migration guide generation
- Impact severity assessment
### api_scorecard.py
Provides comprehensive scoring of API design quality.
**Features:**
- Multi-dimensional scoring
- Detailed improvement recommendations
- Letter grade assessment (A-F)
- Benchmark comparisons
- Progress tracking
## Integration Examples
### CI/CD Integration
```yaml
- name: API Linting
run: python scripts/api_linter.py openapi.json
- name: Breaking Change Detection
run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json
- name: API Scorecard
run: python scripts/api_scorecard.py openapi.json
```
### Pre-commit Hooks
```bash
#!/bin/bash
python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json
if [ $? -ne 0 ]; then
echo "API linting failed. Please fix the issues before committing."
exit 1
fi
```
## Best Practices Summary
1. **Consistency First**: Maintain consistent naming, response formats, and patterns
2. **Documentation**: Provide comprehensive, up-to-date API documentation
3. **Versioning**: Plan for evolution with clear versioning strategies
4. **Error Handling**: Implement consistent, informative error responses
5. **Security**: Build security into every layer of the API
6. **Performance**: Design for scale and efficiency from the start
7. **Backward Compatibility**: Minimize breaking changes and provide migration paths
8. **Testing**: Implement comprehensive testing including contract testing
9. **Monitoring**: Add observability for API usage and performance
10. **Developer Experience**: Prioritize ease of use and clear documentation
## Common Anti-Patterns to Avoid
1. **Verb-based URLs**: Use nouns for resources, not actions
2. **Inconsistent Response Formats**: Maintain standard response structures
3. **Over-nesting**: Avoid deeply nested resource hierarchies
4. **Ignoring HTTP Status Codes**: Use appropriate status codes for different scenarios
5. **Poor Error Messages**: Provide actionable, specific error information
6. **Missing Pagination**: Always paginate list endpoints
7. **No Versioning Strategy**: Plan for API evolution from day one
8. **Exposing Internal Structure**: Design APIs for external consumption, not internal convenience
9. **Missing Rate Limiting**: Protect your API from abuse and overload
10. **Inadequate Testing**: Test all aspects including error cases and edge conditions
## Troubleshooting
| Problem | Cause | Solution |
|---------|-------|----------|
| Linter reports false positives on action endpoints (e.g., `/activate`) | Verb detection flags action segments as REST anti-patterns | Action endpoints are acceptable for non-CRUD operations; suppress with caution or restructure as `POST /resource/{id}/activations` |
| Breaking change detector misses schema-level changes | Input specs lack `components/schemas` definitions or use inline schemas | Ensure both old and new specs define reusable schemas under `components/schemas` for accurate comparison |
| Scorecard gives low security score despite auth being implemented | Security schemes are defined but not applied globally or per-operation | Add a top-level `security` array in the OpenAPI spec and reference `securitySchemes` under `components` |
| Linter exits with code 1 on specs with no endpoints | Zero endpoints with any structural error triggers a non-zero exit | Verify the spec contains at least one path under `paths`; the linter requires endpoints to produce a meaningful score |
| JSON parse error on valid YAML OpenAPI specs | All three tools accept JSON input only | Convert YAML specs to JSON before running tools: `python -c "import yaml,json,sys; json.dump(yaml.safe_load(open(sys.argv[1])),open(sys.argv[2],'w'),indent=2)" spec.yaml spec.json` |
| Naming convention warnings on legacy APIs with snake_case fields | Linter enforces camelCase for properties and kebab-case for URL segments | For brownfield APIs, address naming in new endpoints first and plan a migration for existing fields across a major version bump |
| Scorecard reports 0% for performance category | Spec contains no caching headers, pagination, or compression references | Add `Cache-Control` response headers, define pagination query parameters (`limit`, `offset` or `cursor`), and document compression support |
## Success Criteria
- Zero breaking changes detected between consecutive minor or patch releases (semver compliance)
- API consistency score (from `api_scorecard.py`) above 90 across all reviewed specifications
- Overall scorecard grade of B or higher (80+) before any API ships to production
- 100% of endpoints include at least one success response and one error response definition
- All path segments follow kebab-case naming and all schema properties follow camelCase naming with zero linter errors
- Breaking change reports generated and reviewed for every PR that modifies an OpenAPI spec
- Documentation coverage score above 85%, meaning every operation has a summary and every schema has a description
## Tool Reference
### api_linter.py
**Purpose:** Analyzes OpenAPI/Swagger JSON specifications for compliance with REST conventions and best practices. Checks naming conventions, HTTP method usage, URL structure, status codes, error formats, documentation completeness, and security configuration.
**Usage:**
```bash
python api_linter.py [OPTIONS] INPUT_FILE
```
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `input_file` | positional | Yes | -- | Path to OpenAPI/Swagger JSON file or raw endpoints JSON |
| `--format` | option | No | `text` | Output format: `text` or `json` |
| `--raw-endpoints` | flag | No | off | Treat input as raw endpoint definitions instead of an OpenAPI spec |
| `--output` | option | No | stdout | Write report to the specified file path |
**Example:**
```bash
python api_linter.py openapi.json
python api_linter.py --format json openapi.json > report.json
python api_linter.py --raw-endpoints endpoints.json
python api_linter.py --output lint-report.txt openapi.json
```
**Output Formats:**
- **text** -- Human-readable report with issue breakdown by category, severity icons, suggestions, and a scoring summary. Exits with code 1 if any errors are found, 0 otherwise.
- **json** -- Machine-readable JSON object with `summary` (total_endpoints, endpoints_with_issues, total_issues, errors, warnings, info, score) and `issues` array (severity, category, message, path, suggestion).
---
### breaking_change_detector.py
**Purpose:** Compares two versions of an OpenAPI JSON specification and detects breaking changes including removed endpoints, modified response structures, removed fields, type changes, new required fields, parameter changes, and status code changes. Generates migration guides for each breaking change.
**Usage:**
```bash
python breaking_change_detector.py [OPTIONS] OLD_SPEC NEW_SPEC
```
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `old_spec` | positional | Yes | -- | Path to the old (baseline) API specification JSON file |
| `new_spec` | positional | Yes | -- | Path to the new API specification JSON file |
| `--format` | option | No | `text` | Output format: `text` or `json` |
| `--output` | option | No | stdout | Write report to the specified file path |
| `--exit-on-breaking` | flag | No | off | Exit with code 1 if any breaking changes are detected |
**Example:**
```bash
python breaking_change_detector.py v1.json v2.json
python breaking_change_detector.py --format json v1.json v2.json > changes.json
python breaking_change_detector.py --exit-on-breaking --output report.txt v1.json v2.json
```
**Output Formats:**
- **text** -- Human-readable report listing each change with its type (breaking, potentially_breaking, non_breaking, enhancement), severity (critical, high, medium, low, info), category, path, message, impact description, and migration guide.
- **json** -- Machine-readable JSON object with `summary` (total_changes, breaking_changes, potentially_breaking_changes, non_breaking_changes, enhancements, and per-severity counts) and `changes` array (changeType, severity, category, path, message, oldValue, newValue, migrationGuide, impactDescription).
---
### api_scorecard.py
**Purpose:** Generates a comprehensive API design quality scorecard by evaluating an OpenAPI JSON specification across five weighted dimensions: Consistency (30%), Documentation (20%), Security (20%), Usability (15%), and Performance (15%). Produces letter grades (A-F) per category and overall, with actionable improvement recommendations.
**Usage:**
```bash
python api_scorecard.py [OPTIONS] SPEC_FILE
```
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `spec_file` | positional | Yes | -- | Path to the OpenAPI/Swagger specification JSON file |
| `--format` | option | No | `text` | Output format: `text` or `json` |
| `--output` | option | No | stdout | Write scorecard to the specified file path |
| `--min-grade` | option | No | none | Minimum acceptable grade (`A`, `B`, `C`, `D`, `F`); exits with code 1 if the overall grade falls below this threshold |
**Example:**
```bash
python api_scorecard.py openapi.json
python api_scorecard.py --format json openapi.json > scorecard.json
python api_scorecard.py --min-grade B --output scorecard.txt openapi.json
```
**Output Formats:**
- **text** -- Human-readable scorecard showing API info, per-category scores with letter grades, issue counts, recommendations, and an overall weighted score with grade.
- **json** -- Machine-readable JSON object with `apiInfo`, `categoryScores` (per category: score, maxScore, weight, letterGrade, weightedScore, issues, recommendations), `overallScore`, `overallGrade`, `totalEndpoints`, and `topRecommendations`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |