Documentation — Apibreak OpenAPI Breaking Change Detector

What Apibreak Is

Apibreak is a client-side-only OpenAPI/Swagger breaking-change detector. You paste or upload two versions of an API specification — yesterday's and today's, main and a branch, one tag and another — and the browser parses both, performs a semantic structural diff (not a text diff), and classifies every difference into three buckets:

BREAKING — A relying client stops working. Removed endpoint, deleted response field, parameter made required, type narrowed, status code removed.
ADDITIVE — New surface, old clients unaffected. New endpoint, new optional parameter, new response field. Safe to deploy.
COSMETIC — No semantic effect. Description rewording, example change, property reordering. Counted, not individually listed.

Everything runs locally in the browser. No spec data ever leaves your machine. No account, no sign-up, no server-side storage.

How the Diff Engine Works

The engine does not read the spec as text. It parses both documents into a structured internal representation, then compares them node by node.

1. Parse and validate

Accepts JSON and YAML. Loads js-yaml from CDN for YAML parsing; uses native JSON.parse for JSON. Rejects anything that is not a valid OpenAPI 3.x or Swagger 2.0 document with a clear error message.

2. Normalize and resolve

Both specs are normalised to a common internal representation: $refs resolved from components/schemas (OpenAPI 3.x) or definitions (Swagger 2.0), Swagger 2.0 structures aligned with the OpenAPI 3.x shape, descriptions and examples stripped for structural comparison. Each spec becomes a schema tree.

3. Walk and classify

Every difference is detected at four levels and classified:

Path+method level: endpoint added, removed, or renamed
Parameter level: parameter added, removed, type changed, requiredness changed, default removed
Request body / response level: status code changes, content type changes, schema property added/removed/type-narrowed
Schema property level: property removed, type narrowed (string → enum), property made required, property made nullable (or vice versa)

4. Render and export

Results shown in three collapsible sections with before/after values for each breaking change. Copy as Markdown with one click, or download as a .md file.

How to Use Apibreak

No account, no installation. Open the app and compare two specs in under a minute.

Open the app.

Navigate to apibreak.agen2ic.ai/app in any modern browser. The tool loads immediately — nothing to install, no sign-up.
Prepare two spec versions.

From your repository: git show HEAD~1:openapi.yaml > spec-old.yaml and git show HEAD:openapi.yaml > spec-new.yaml. Both specs must be fully self-contained — all $refs must resolve within the file.
Paste or upload.

Paste Spec A (old/yesterday) into the left textarea and Spec B (new/today) into the right textarea. Alternatively, click Upload file above each panel to load from disk. The tool accepts JSON and YAML, OpenAPI 3.x and Swagger 2.0.
Click Compare.

Click the Compare button or press Ctrl+Enter. The engine parses both specs, resolves $refs, walks the schema tree, and classifies every difference.
Read the report.

Breaking changes appear first (most important), then additive, then cosmetic (counted only). Each breaking change shows the path, method, what changed, and before/after values. Use Copy report to grab Markdown for a PR comment, or Download .md to save a file.

The Three Buckets — Reference

Bucket	Meaning	Examples	Visual
BREAKING	An existing client stops working on the new spec. A change that the old client did not expect and cannot handle.	Endpoint removed Path parameter renamed Response field removed Parameter made required Type narrowed (string → enum) Status code removed Default value removed	Red
ADDITIVE	New capability that existing clients ignore. Old clients continue to function without changes.	New endpoint New optional parameter/header New response body field New status code Type widened (enum → string)	Green
COSMETIC	No effect on the API contract. Purely informational changes that do not affect clients. Counted, not individually listed.	Description rewording Example value changed Property reordering Version bump Server URL change Whitespace/formatting	Grey

What Apibreak Does NOT Do

These are design boundaries, not future features. Apibreak is a focused diagnostic tool:

Does not fetch specs from URLs or repositories. Paste or upload file content only. No GitHub, GitLab, Bitbucket, or any URL-based input.
Does not store anything. Spec content exists only in browser memory. Refresh the page or navigate away — everything is gone. No localStorage, no server-side persistence, no database.
Does not call any external service. The entire analysis runs client-side. No API calls, no analytics, no data exfiltration. Your spec never leaves your machine.
Does not judge whether a breaking change is justified. Apibreak classifies each change into a bucket. It does not decide whether the break is acceptable, how to mitigate it, or which team should approve it. That is a human decision.
Does not offer CI integration. No CLI, no GitHub Action, no webhook, no programmatic API. Apibreak is a browser-based analysis tool.
Does not email results. There is no email sender. Use Copy or Download to share reports.
Does not process real payments. The checkout on the pricing page is connected to Stripe in test mode. No real payment is processed. Pro features are not yet implemented.

Input & Output Reference

Accepted input formats

Format	Spec versions	Source
JSON (.json)	OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0	Paste text or upload file
YAML (.yaml, .yml)	OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0	Paste text or upload file

Output channels

Channel	Description
Screen	Categorized report rendered on the page with three collapsible sections. Breaking changes show path, method, before/after values.
Copy	Button copies a formatted Markdown report to clipboard via navigator.clipboard.writeText().
Download	Button triggers download of the report as a .md file via Blob + URL.createObjectURL().

Example fixtures

The app includes built-in fixtures accessible via Load examples buttons on the app page:

Petstore v1 / v2 — OpenAPI 3.x pair with known BREAKING, ADDITIVE, and COSMETIC changes
Swagger v1 / v2 — Swagger 2.0 equivalent pair for cross-format testing
Invalid JSON / Invalid YAML — Malformed documents to verify error handling

Known Limitations

Apibreak is a best-effort structural analysis tool. The following are documented limitations of the current build:

$refs must be internal. References that point to external files or URLs cannot be resolved. The spec must be fully self-contained (bundled). Consider diffing bundled specs.
Composition keywords (oneOf/anyOf/allOf) are treated as schema-level changes. The composite schema is compared as a whole, not decomposed. Individual member changes may not be detected.
OpenAPI 3.1 JSON Schema edge cases. The 3.1 revision adopted full JSON Schema 2020-12, which introduces keywords not present in OpenAPI 3.0's subset. Some changes involving these keywords may produce unexpected classifications.
Large specs may cause brief UI delay. Specs with more than ~5,000 paths may cause a noticeable pause during processing. The engine uses setTimeout chunking to prevent the browser from freezing, but the wait is not instant.
Custom extensions are not analysed. Properties starting with x- are structural noise — the engine does not classify them.
Format conversion (Swagger 2.0 → OpenAPI 3.0) shows BREAKING changes. If you diff a Swagger 2.0 spec against an OpenAPI 3.0 version, every structural difference (e.g., definitions → components/schemas, parameter in: body → requestBody) will appear as BREAKING. This is correct behaviour — the format change IS a breaking change for a client that parsed the old structure.
No multi-file bundling. Tools like redocly bundle should be used to produce a single-file spec before diffing.
Pro features are not implemented. The Pro tier (batch comparison, collapsible diff trees, comparison history) is listed on the pricing page as a planned offering. The checkout form is a Stripe test-mode demonstration. No real payment is processed.

Important: The classification engine is a best-effort analysis and is not infallible. The report is not a substitute for human review. If you believe a classification is incorrect, email apibreak@agen2ic.ai with the two specs (or a minimal reproduction) and we will investigate.

Technical Architecture

Apibreak is a fully static site. The architecture is minimal by design:

No server-side compute. All logic — parsing, validation, $ref resolution, structural diff, classification, rendering — executes in the browser. No Worker API routes exist.
No database. No state persists beyond the current page view. Refresh the page and everything is gone.
No cron jobs or scheduled work. Nothing runs when nobody has the page open.
Single static Worker serves the asset tree (HTML, CSS, JS, fixtures, images). It has no API routes and emits no Content-Security-Policy header (CSP is defined in a <meta> tag on each page).
One external dependency: js-yaml v4.x loaded from cdnjs.cloudflare.com for YAML parsing. JSON parsing uses the native browser API.
No user tracking. No analytics scripts, no cookies, no fingerprinting. The only network requests are for web fonts (Google Fonts via fonts.gstatic.com) and the font stylesheet.

How Apibreak works, end to end.