API Design Review and Detecting Breaking Changes: A Complete Guide to the Claude Skills OpenAPI Toolkit

The Claude Skills repository provides a production-ready API Design Reviewer skill that lints OpenAPI specifications, scores design quality, and automatically detects breaking changes between API versions using pure Python and zero external dependencies.

This guide explores the alirezarezvani/claude-skills repository's modular approach to API governance. Whether you are maintaining a public REST API or managing internal microservices, understanding how to automate API design review and detect breaking changes ensures semantic versioning discipline and prevents accidental client breakage.

Repository Architecture and Skill Structure

The API Design Reviewer follows the skill-package pattern defined in the repository's CLAUDE.md. Each skill is self-contained, lives in its own directory, and includes a SKILL.md file that serves as the single source of truth for usage and capabilities.

Key files in engineering/api-design-reviewer/:

• SKILL.md – Human-readable skill description, versioning policy, and integration points
• scripts/api_linter.py – Rule-based static analysis for naming conventions, HTTP verbs, and security headers
• scripts/breaking_change_detector.py – Core diff engine that compares two OpenAPI specs and classifies changes
• scripts/api_scorecard.py – Weighted quality calculator producing letter grades (A-F) and actionable improvements
• .github/workflows/ci-quality-gate.yml – CI gate that enforces linting and breaking-change detection on every push

All scripts rely exclusively on Python 3's standard library, making them portable across any environment without pip installations.

Core Component: The Breaking Change Detector

The breaking_change_detector.py script is the most sophisticated component for API design review and detecting breaking changes. It performs a granular, section-wise comparison of two OpenAPI JSON or YAML files.

Change Classification System

The detector uses two enum classifications to categorize every modification:

ChangeType enum:

• BREAKING – Removes or modifies existing contracts (e.g., deleting an endpoint, making a field required)
• POTENTIALLY_BREAKING – Changes that may break certain clients (e.g., adding enum values)
• NON_BREAKING – Additive changes that preserve backward compatibility
• ENHANCEMENT – Documentation or metadata improvements

ChangeSeverity enum:

• CRITICAL, HIGH, MEDIUM, LOW, INFO

Granular Diff Logic

For each path in the OpenAPI spec, the detector examines:

1. Endpoint existence – Addition or removal of entire paths
2. HTTP method changes – New or removed operations on existing paths
3. Parameter modifications – Required-to-optional transitions, type changes, or default value alterations
4. Request body requirements – Toggling required status on request bodies
5. Response schema evolution – Status code changes, property additions/removals, and required field modifications in response objects
6. Security requirement drift – Changes to authentication schemes or scopes

Helper functions like _compare_schemas() and _compare_object_properties() recursively traverse schema definitions to detect nested type changes that could break deserialization in client SDKs.

Migration Guidance Generation

Unlike simple diff tools, the detector generates migration guidance for every breaking change. When it detects a removed endpoint, it suggests alternative paths. When a required field is added, it notes the specific client impact. This guidance is included in both human-readable text reports and machine-parsable JSON outputs.

Static Analysis with the API Linter

The api_linter.py script enforces REST best practices through a series of rule checks that emit Change objects with NON_BREAKING type and INFO severity. These rules cover:

• Naming conventions – Kebab-case for resource paths, camelCase for schema fields
• HTTP verb validation – Correct use of GET, POST, PUT, PATCH, and DELETE semantics
• URL structure – Collection versus item path patterns, avoiding verb-based URLs like /getUsers
• Status code coverage – Ensuring appropriate 2xx, 4xx, and 5xx responses are documented
• Error format consistency – Verifying a uniform error object schema across all endpoints
• Documentation completeness – Flagging missing description fields on parameters and responses

Quality Scorecard Implementation

The api_scorecard.py aggregates findings from both the linter and breaking-change detector into a weighted percentage score:

Weight	Category	Evaluation Criteria
30%	Consistency	Naming, URL patterns, HTTP verb usage
20%	Documentation	Presence of descriptions, examples, and external docs
20%	Security	Auth schemes, security headers, rate-limit hints
15%	Usability	Pagination strategies, idempotency keys, HATEOAS links
15%	Performance	Caching hints, pagination efficiency, compression hints

The final output includes a letter grade (e.g., B-) and a prioritized list of high-impact improvements.

Practical Usage Examples

Linting a Single OpenAPI File

python engineering/api-design-reviewer/scripts/api_linter.py openapi/v1.json

The output displays style violations with file-line references for quick remediation.

Detecting Breaking Changes Between Versions

Generate a human-readable text report:

python engineering/api-design-reviewer/scripts/breaking_change_detector.py \
    specs/v1.json specs/v2.json

Produce a machine-parsable JSON report for downstream automation:

python engineering/api-design-reviewer/scripts/breaking_change_detector.py \
    --format json specs/v1.json specs/v2.json > breaking_report.json

Enforce semver discipline by exiting with code 1 when breaking changes are detected:

python engineering/api-design-reviewer/scripts/breaking_change_detector.py \
    --exit-on-breaking specs/v1.json specs/v2.json

Generating a Design Scorecard

python engineering/api-design-reviewer/scripts/api_scorecard.py specs/v2.json

This outputs the calculated grade and specific recommendations for improving API consistency and security posture.

CI/CD Integration for Automated Enforcement

The repository includes .github/workflows/ci-quality-gate.yml, which demonstrates how to integrate API design review and detecting breaking changes into your deployment pipeline.

steps:
  - name: Checkout code
    uses: actions/checkout@v3

  - name: Run API Linter
    run: |
      python engineering/api-design-reviewer/scripts/api_linter.py \
        openapi/current.json

  - name: Detect Breaking Changes
    run: |
      python engineering/api-design-reviewer/scripts/breaking_change_detector.py \
        openapi/previous.json openapi/current.json --exit-on-breaking

When the detector flags a BREAKING change with CRITICAL or HIGH severity, the workflow aborts. This forces developers to either bump the major version number or create a formal migration guide before merging to main or dev branches.

Summary

• Zero-dependency implementation – The API Design Reviewer runs on pure Python 3 without external libraries, making it ideal for locked-down CI environments.
• Comprehensive change detection – The breaking_change_detector.py analyzes paths, methods, parameters, request bodies, response schemas, and security requirements, not just simple structural diffs.
• Automated semver enforcement – The --exit-on-breaking flag ensures that any modification breaking the contract fails the build, maintaining strict semantic versioning discipline.
• Extensible architecture – Core classes like BreakingChangeDetector, Change, and ComparisonReport can be subclassed to implement custom organizational rules while retaining standard reporting formats.
• Holistic quality metrics – The scorecard provides objective letter grades based on consistency, documentation, security, usability, and performance criteria.

Frequently Asked Questions

How does the breaking change detector classify a change as breaking versus non-breaking?

The detector uses the ChangeType enum defined in breaking_change_detector.py to classify modifications. BREAKING changes include endpoint removals, making optional parameters required, altering response schemas, or changing existing status codes. NON_BREAKING changes include additive operations like new optional fields or new endpoints. The logic examines the actual API contract impact—for example, _compare_schemas() recursively checks if a property changed from optional to required, which would break existing clients that omit that field.

Can I integrate the API linter into a pre-commit hook instead of CI?

Yes. Because api_linter.py requires only Python 3 and accepts file paths as arguments, you can add it to a pre-commit configuration or local git hook. Run python engineering/api-design-reviewer/scripts/api_linter.py <spec-file> before each commit to catch naming convention violations or missing documentation locally before pushing to the repository.

What output formats does the breaking change detector support?

The detector supports two output formats controlled by the --format flag. By default, it produces human-readable text reports with migration guidance. When --format json is specified, it emits a structured JSON payload containing the list of Change objects with their ChangeType, ChangeSeverity, location in the spec, and suggested fixes. This JSON format is suitable for feeding into ticketing systems, PR comment bots, or compliance dashboards.

Does the scorecard require both the linter and breaking change detector to run first?

No. The api_scorecard.py script operates independently and can analyze a single OpenAPI specification without comparison to a previous version. However, when used in the complete workflow demonstrated in ci-quality-gate.yml, it typically aggregates findings from both the linter (style issues) and the breaking change detector (contract stability) to provide a comprehensive quality grade. The scorecard weights consistency and documentation higher than performance, reflecting that API stability and clarity generally impact developer experience more than optimization hints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}