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

> Master API design review and detect breaking changes with the Claude Skills OpenAPI Toolkit. This pure Python tool offers production-ready linting and version comparison for better API quality.

- Repository: [Alireza Rezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)
- Tags: api-reference
- Published: 2026-03-09

---

**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`](https://github.com/alirezarezvani/claude-skills/blob/main/CLAUDE.md). Each skill is self-contained, lives in its own directory, and includes a [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) file that serves as the single source of truth for usage and capabilities.

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

- [`SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/SKILL.md) – Human-readable skill description, versioning policy, and integration points
- [`scripts/api_linter.py`](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/api_linter.py) – Rule-based static analysis for naming conventions, HTTP verbs, and security headers
- [`scripts/breaking_change_detector.py`](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/breaking_change_detector.py) – Core diff engine that compares two OpenAPI specs and classifies changes
- [`scripts/api_scorecard.py`](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/api_scorecard.py) – Weighted quality calculator producing letter grades (A-F) and actionable improvements
- [`.github/workflows/ci-quality-gate.yml`](https://github.com/alirezarezvani/claude-skills/blob/main/.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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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

```bash
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:

```bash
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:

```bash
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:

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

```

### Generating a Design Scorecard

```bash
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`](https://github.com/alirezarezvani/claude-skills/blob/main/.github/workflows/ci-quality-gate.yml), which demonstrates how to integrate API design review and detecting breaking changes into your deployment pipeline.

```yaml
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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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.