API Breakage Radar

Detect API response structure changes before they become integration problems.

PixelcraftDev · Official website · Free desktop Beta 0.2.8

Third-party APIs may change unexpectedly. Missing fields and changed data types can create integration problems. API Breakage Radar compares the observed structure of a saved JSON response baseline with a later response, helping you investigate differences from inside VS Code. It does not prove that your application code is broken.

Features

• Configure multiple JSON GET endpoints with individual authentication and 1–60 second timeouts.

• Save an explicitly approved baseline and compare later responses manually.

• Inspect added/missing fields, nested objects, type/null transitions and sampled array structure.

• Review local reports and export JSON/Markdown with field names pseudonymized.

• Keep configuration and encrypted baselines across restarts, provided local storage and SecretStorage remain available.

• Use an English/Thai manual with offline Noto Sans Thai.

Getting Started

1. Install the supplied VSIX: open the Command Palette and choose Extensions: Install from VSIX… . Marketplace publication has not been confirmed.

2. Open API Breakage Radar in the activity bar. Choose Quick actions / เมนูใช้งาน or User Manual / คู่มือใช้งาน for guidance.

3. Choose Add API. Example name: Products API; URL: https://api.example.com/products (placeholder only—replace it with your reachable API). Method is GET; default timeout is 10 seconds.

4. Choose No authentication, Bearer token, or Custom headers / API key. In Review & save, use Change timeout if needed (1–60 seconds), then Save endpoint. Adding does not send a request.

5. Expand the saved API and choose Save first baseline. Approve the request, inspect the structural preview, then confirm Save Baseline. This starting structure is your comparison reference.

6. Choose Check for changes and approve a later request. This compares the new sample with the saved baseline without replacing it.

7. Choose Open full report to inspect findings and Before / After. Use Report actions → Export private-safe report for JSON or Markdown. Use this result as new baseline requires a separate confirmation.

Use the supplied api-breakage-radar-SupapongSakulkoo-0.2.8.vsix. The illustrated manual opens in English, with circular US/Thai controls and bundled Noto Sans Thai. Sidebar labels above are exact; Command Palette equivalents are Capture Baseline, Check for Changes, Send Test Request, View Last Raw Response, View Latest Report, and Export Report, under API Breakage Radar.

Real-World Use Cases

These synthetic examples are tested against the actual comparison engine. Paths use JSON Pointer.

E-commerce supplier API

Problem: A supplier response changes while your product integration expects price.

Original JSON response:

{
  "product_id": 101,
  "name": "Keyboard",
  "price": 99
}

Updated JSON response:

{
  "product_id": 101,
  "name": "Keyboard",
  "amount": 99
}

Expected structural findings: /price missing; /amount added.

Developer benefit: Investigate price mapping before importing the next catalog.

Limitations: These are separate findings, not a confirmed rename.

Payment gateway type change

Problem: Your payment integration expects a string status.

Original JSON response:

{
  "payment_id": "TX001",
  "status": "success"
}

Updated JSON response:

{
  "payment_id": "TX001",
  "status": {
    "code": "success",
    "verified": true
  }
}

Expected structural findings: /status changes from string to object.

Developer benefit: Review code that reads the payment status.

Limitations: The difference alone does not prove a payment failed or application code broke.

Financial API with nested JSON

Problem: A price integration expects a nested sell field.

Original JSON response:

{
  "gold": {
    "price": {
      "buy": 72500,
      "sell": 72600
    }
  }
}

Updated JSON response:

{
  "gold": {
    "price": {
      "buy": 72500,
      "selling": 72600
    }
  }
}

Expected structural findings: /gold/price/sell missing; /gold/price/selling added.

Developer benefit: Identify which nested mapping needs investigation.

Limitations: No confirmed rename or validation of price accuracy is implied.

Sports API missing field

Problem: A score widget expects a home_score field.

Original JSON response:

{
  "match_id": 501,
  "home_score": 2,
  "away_score": 1
}

Updated JSON response:

{
  "match_id": 501,
  "away_score": 1
}

Expected structural findings: /home_score is missing from the latest observed response.

Developer benefit: Investigate whether the widget handles absent scores.

Limitations: The field may be optional. This does not prove permanent removal from the provider contract.

SaaS with multiple external APIs

Problem: A SaaS integrates separate billing and CRM endpoints. Add each endpoint with its own name, authentication and baseline; run Check for changes separately. This JSON pair represents only the CRM endpoint.

Original JSON response:

{
  "customer": {
    "id": 10,
    "tier": "pro"
  }
}

Updated JSON response:

{
  "customer": {
    "id": 10,
    "tier": {
      "name": "pro"
    }
  }
}

Expected structural findings: /customer/tier changes from string to object for CRM. No finding about billing follows from this check.

Developer benefit: Investigate findings independently for each configured endpoint.

Limitations: Checks are manual. There is no monitoring dashboard, automatic polling or historical response browser.

Backend deployment regression investigation

Problem: After a backend deployment, a consumer still expects user.email.

Original JSON response:

{
  "user": {
    "id": 10,
    "email": "user@example.com"
  }
}

Updated JSON response:

{
  "user": {
    "id": 10
  }
}

Expected structural findings: /user/email missing.

Developer benefit: Use the observed difference as evidence when investigating the deployment.

Limitations: This is not complete regression-test coverage and does not locate affected source lines.

Understanding Results

• Added fields (INFO): newly observed, not guaranteed harmless to strict consumers.
• Missing fields (WARNING): absent in this sample; they may be optional. Permanent removal is not established.
• Type changes (HIGH): for example, 99 → "99". Null transitions and array item-structure differences are also reported; uncertain samples use UNKNOWN.
• No structural changes: same observed structure; ordinary value changes such as 99 → 100 are ignored. This does not guarantee the entire contract is unchanged.
• HTTP/request failures: not evidence of schema change. Failed requests preserve the saved baseline and latest successful report. Successful HTTP status differences are separate warnings.

Authentication and Privacy

Choose No authentication, Bearer token, or Custom headers / API key. There is no OAuth login flow or token refresh. Update Credentials can keep saved authentication; Clear Saved Credentials clears the URL too.

Requests go directly to your endpoint only after your action and confirmation. URLs and headers use VS Code SecretStorage; structural state is encrypted locally. No telemetry, cloud upload or workspace scanning. Raw response values may be shown in the editor for the current session after a request, but are not persisted to encrypted storage or baselines; field names in stored shapes can still be sensitive. Exports pseudonymize field names and omit URLs, credentials and API aliases; structural patterns and timing/status remain visible. Export private-safe report does not mean all information is anonymous.

See Technical guide (docs/TECHNICAL_GUIDE.md) and Security and privacy (docs/SECURITY_PRIVACY.md) for storage recovery, request consent, redirect/TLS behavior, export limits and upgrade details.

Frequently Asked Questions

Does this detect application crashes?

No. It compares observed JSON structures, not application execution.

Does this monitor APIs automatically?

No. Each request requires a manual action and confirmation.

Does this detect ordinary value changes?

No. 99 → 100 is ignored. 99 → "99" is a number-to-string type change.

Does a missing field always mean a breaking change?

No. It may be optional or absent only in this sample.

Does it support authenticated APIs?

Yes: Bearer token or Custom headers / API key. No built-in OAuth login or token refresh.

Can it run while VS Code is closed?

No. There is no background monitoring service.

Can it identify affected source-code lines?

No. Source scanning and Code Impact Detection are not implemented.

Can I use my own API endpoints?

Yes. Configure a reachable JSON GET endpoint and its credentials. Requests run from the desktop where the extension runs.

Current Limitations

JSON over GET or POST only; no other methods, automatic monitoring, source-code analysis or full contract validation. POST bodies must be JSON up to 64 KiB. Maximum response 2 MiB, first 100 array items, 20,000 inference nodes and 48 nesting levels. Mixed/empty arrays may be uncertain. Redirects and compressed responses are rejected. A successful comparison covers only the observed sample. The old 1.95.3 test app has a known locally reproduced Webview failure; the manual was verified in the installed VS Code 1.136.1. Other editors and marketplaces are not certified.

No endpoint-count paywall; response/storage safety limits still apply. Configuration and encrypted baselines persist across restarts, but losing SecretStorage keys can make state unrecoverable.

Development and Testing

Node 22 and npm are used for development.

npm ci
npm run build
npm run lint
npm test
npm run test:integration
npm run package

Press F5 from the project for Extension Development Host. The integration harness defaults to VS Code 1.95.3; override with RADAR_VSCODE_VERSION. That old test app reproduced a Webview service-worker error locally; use the tested standard VS Code 1.136.1 for manual UI checks. The automated suite is not a substitute for full native-host release QA.

Run node scripts/mock-api.cjs from the source folder, choose 1 for baseline, 2 for changed, 3 for HTTP 500, or 0 to quit. Each change still requires a manual extension check. The mock script is not included in the VSIX.

See QA (QA.md), technical modules and comparison rules (docs/TECHNICAL_GUIDE.md), and documentation audit (docs/DOCUMENTATION_AUDIT_0.2.5.md).

Future Roadmap

Current Free features

The features listed above are implemented. No account or paid activation is required.

Planned Pro features

Planned Pro ideas only: automatic monitoring, Code Impact Detection, Regression Test Generation, richer change history, CI/CD integration and team collaboration. None is shipped or offered for purchase. The Free runtime has a bounded local event log, not historical response browsing. No activation or upgrade is required for current Free features.

See Pro architecture proposal (docs/PRO_ARCHITECTURE.md).

License and Credits

Proprietary free-use license: official unmodified copies are free for personal and commercial use. First-party source modification, redistribution and resale require permission, subject to applicable law. See LICENSE.txt (LICENSE.txt). Third-party licenses remain unchanged; your data and generated reports remain yours.

Publisher: SupapongSakulkoo. Brand: PixelcraftDev. Sweetie radar mascot selected by the owner; local monochrome activity-bar icon retained. Noto Sans Thai is bundled under SIL OFL 1.1 (media/fonts/OFL.txt). See Third-party notices (THIRD_PARTY_NOTICES.md).

Publication is not confirmed. This task does not publish to Marketplace or Open VSX.

Developer document paths above refer to files included in the extension/source package. No public source repository is configured.

Select and inspect an endpoint

Use Quick actions → Select API to test / เลือก API เพื่อทดสอบ to choose a saved API, then capture its first baseline or check changes with the normal confirmations. Each API has an Endpoint URL eye control: click to reveal the full saved URL, click again to hide. URLs start hidden after reload and are never included in reports or logs. Authentication headers are not displayed; query parameters in the revealed URL can still be sensitive.

Send test request edits query/path arguments for one GET (Postman-style), then opens the raw JSON response in the editor. View last raw response reopens the latest body from session memory only — raw values are not written to encrypted storage or baselines.