📦 Installation
API Contract Guardian is available on the Visual Studio Marketplace.
Install from VS Code
- Open Visual Studio Code.
- Open the Extensions panel using
Ctrl + Shift + X.
- Search for API Contract Guardian.
- Select API Contract Guardian by komallsingh.
- Click Install.

You can also visit the API Contract Guardian Marketplace page to view the extension and install it.
Install from VSIX
You can also download the .vsix file from the project's GitHub Releases and install it manually:
- Open the Extensions panel in VS Code.
- Click the ... menu.
- Select Install from VSIX....
- Choose the downloaded
.vsix file.
Overview
APIs often evolve faster than their consumers.
An endpoint may be removed, a response field may disappear, or a response type may change without an obvious signal to the developer working on the API.
API Contract Guardian analyzes API contracts across Git revisions and surfaces potentially breaking changes directly inside VS Code.
Instead of discovering compatibility problems at runtime, developers can identify contract changes while working on the codebase.
Guardian detects
- Removed API endpoints
- Removed response fields
- Response field type changes
- Potentially affected JavaScript and TypeScript consumers
- Added, modified, and deleted API source files
- Cross-file Express router composition
- Nested router mounts
- JavaScript and TypeScript module relationships
- Static route discovery for supported FastAPI routers and Flask blueprints
- Python relative-import and package re-export relationships
- API contract differences across Git revisions
What Problem Does It Solve?
Consider an API that originally returns:
{
"id": 1,
"name": "Komal",
"email": "komal@example.com"
}
If email is removed in a later revision, existing consumers that depend on that field may break even though the server still starts successfully.
Guardian uses the previous Git revision as a source of the previous API contract and compares it with the current repository.
The result is a development-time signal for potentially breaking API changes.
Why API Contract Guardian?
Git-aware
Git already contains previous versions of the source code.
Guardian uses Git revisions to derive and compare API contracts instead of requiring developers to manually maintain historical contracts.
Static analysis
Guardian analyzes JavaScript, TypeScript, and a supported subset of Python source code rather than executing the application.
This allows contract analysis during development without requiring the API server to be running.
Repository-wide discovery
V2 analyzes the repository as a connected system rather than treating every API source file independently.
An API can be distributed across multiple modules, imports, exports, routers, and mount points.
Structure-based detection
Guardian does not depend on fixed endpoint names or variable names such as app or router.
It analyzes the structure and relationships of the source code to identify Express applications, routers, routes, and mounts.
V1 — Core API Contract Detection
V1 established the foundation of Guardian: it inspects API source files for route definitions and response payloads, compares the previous and current Git revisions, and reports breaking contract changes directly in VS Code.
V1 capabilities
- [x] Detect removed API endpoints
- [x] Detect removed response fields
- [x] Detect changed response field types
- [x] Extract response contracts from
res.json() patterns
- [x] Identify potentially affected JavaScript and TypeScript consumers
- [x] Compare Git revisions
- [x] Report findings through the VS Code Problems panel
- [x] Support JavaScript and TypeScript source analysis
- [x] Perform file-level API contract comparison
flowchart LR
A["Git revision"] --> B["API source files"]
B --> C["Route detection"]
C --> D["Response contract extraction"]
D --> E["API contract model"]
E --> F["Compare prior vs current contract"]
F --> G["Breaking changes"]
G --> H["Consumer analysis"]
H --> I["VS Code diagnostics"]
V1 provided the baseline contract-comparison model that later versions extended to repository-wide discovery and route composition.
V2 — Repository-Wide API Discovery
V2 expands Guardian from file-level analysis to repository-wide discovery. Instead of evaluating each API file in isolation, it indexes source files, resolves imports and exports, detects Express apps and routers, composes nested mounts, and compares the resulting API contracts across Git revisions.
V2 capabilities
- [x] Repository-wide source discovery
- [x] Recursive JavaScript and TypeScript source discovery
- [x] Generated/dependency directory filtering
- [x] Cross-file module indexing
- [x] Relative import resolution
- [x] JavaScript and TypeScript extension resolution
- [x]
index.js / index.ts module resolution
- [x] Default and named imports/exports
- [x] Express application and router detection
- [x]
express.Router() detection
- [x] Route detection without fixed variable names
- [x]
app.use()-style mount detection
- [x] Router-to-router mounts
- [x] Nested router composition
- [x] Multiple mounts of the same router
- [x] Final composed route paths
- [x] Repository-wide API contract discovery
- [x] Git revision comparison
- [x] Consumer impact analysis
- [x] VS Code diagnostics
flowchart TD
A["Git revision"] --> B["Repository discovery"]
B --> C["Source file loading"]
C --> D["Module indexing + import resolution"]
D --> E["Express app / router detection"]
E --> F["Route + mount detection"]
F --> G["Cross-file route composition"]
G --> H["API contract extraction"]
H --> I["Compare previous vs current contracts"]
I --> J["Breaking changes"]
J --> K["Consumer impact analysis"]
K --> L["VS Code diagnostics"]
The major architectural change in V2 is that discovery happens across the repository before comparison, which allows Guardian to reason about APIs that span multiple files and router layers.
V3 — Python Route Discovery
V3 adds static Python route discovery for supported FastAPI and Flask patterns. The repository-aware analysis can discover routes across related files where the routing structure is statically clear, including common FastAPI router composition and Flask blueprint-style registration patterns.
V3 capabilities
- [x] Python file detection
- [x] FastAPI-style route detection for common decorator patterns
- [x] Flask-style route detection for common decorator patterns
- [x] Static route composition for supported repository patterns
- [x] Python contract extraction for supported route implementations
- [x] Git-aware comparison for supported Python APIs
- [x] Integration with the same VS Code diagnostics workflow
Python static-analysis limitations
Python support is intentionally conservative and statically based. Guardian does not execute Python applications, and it does not attempt to resolve every possible dynamic framework pattern or runtime-generated route. Supported behavior is limited to the patterns that are reliably detectable in the source code, such as common FastAPI and Flask decorator usage and straightforward route composition. Dynamic imports, non-standard framework conventions, and highly dynamic Python routing may not be fully inferred.
flowchart LR
A["Project scan"] --> B["Python source discovery"]
B --> C["Decorator + route detection"]
C --> D["FastAPI / Flask pattern matching"]
D --> E["Repository-aware route composition"]
E --> F["Python API contracts"]
F --> G["Contract comparison"]
G --> H["Breaking changes + diagnostics"]
Python support follows Guardian’s static-analysis model; it is not a full runtime Python API analysis engine.
V1 → V2 → V3 Evolution
| Version |
Primary focus |
Key capabilities |
Key constraint |
| V1 |
Core contract detection |
Route extraction, response-field comparison, Git-based diffing, VS Code diagnostics |
File-level analysis |
| V2 |
Repository-wide discovery |
Cross-file module resolution, route composition, nested mounts, repository-wide contract discovery |
JavaScript / TypeScript static analysis |
| V3 |
Python route discovery |
Supported FastAPI and Flask route discovery, repository-aware route composition, Python contract comparison |
Static analysis only; not full dynamic Python runtime analysis |
The evolution is straightforward: V1 established the contract model, V2 expanded discovery across the repository, and V3 added supported Python patterns to the same comparison-and-diagnostics workflow.
Core Architecture Workflow
flowchart TD
A["Project scan"] --> B["Repository discovery"]
B --> C["Source file loading"]
C --> D["Language parser selection"]
D --> E["JavaScript / TypeScript / Python analysis"]
E --> F["Route + mount + import resolution"]
F --> G["API contract extraction"]
G --> H["Compare previous vs current contracts"]
H --> I["Breaking change detection"]
I --> J["Consumer impact analysis"]
J --> K["VS Code diagnostics"]
Example
Contract Change
An API initially returns:
{
"id": 1,
"name": "Komal",
"email": "komal@example.com"
}
A later Git revision removes email.
Guardian compares the two contracts and reports:
Response field "email" was removed from GET /api/v1/customers
If a statically detectable consumer accesses data.email, Guardian can additionally report potential consumer impact.
V2 Example — Cross-File Routing
V2 can resolve an API distributed across multiple files:
server.ts
|
+-- app.use("/api", apiRouter)
|
+-- apiRouter.use("/v1", customerRouter)
|
+-- GET "/customers"
Guardian resolves the composed route as:
GET /api/v1/customers
This allows the contract comparison engine to work with the actual API path rather than treating each source file in isolation.
Supported API Patterns
Express
Guardian currently supports statically detectable Express-style patterns including:
express()
express.Router()
- Express application routes
- Express router routes
- HTTP methods such as
get, post, put, patch, and delete
res.json({...})
app.use()-style mounts
- Router-to-router mounts
Modules
Guardian supports:
- Relative imports
- Default imports
- Named imports
- Default exports
- Named exports
- JavaScript/TypeScript extension resolution
index.js / index.ts module resolution
Route Composition
Guardian can compose routes across multiple mount levels.
For example:
/api
+ /v1
+ /customers
becomes:
/api/v1/customers
The same router can also be mounted at multiple paths.
Git Comparison
Guardian uses Git revisions as the source of historical API contracts.
Previous Git Revision
|
v
Previous API Contract
Current Git Revision
|
v
Current API Contract
|
v
Contract Comparison
|
v
Potential Breaking Changes
V2 performs repository-wide discovery for the revisions being compared.
This is important because an API route may depend on several source files, while only some of those files may have changed.
Consumer Impact Analysis
Guardian can identify statically detectable JavaScript and TypeScript consumers that access changed response fields.
For example, if an API response field is removed and a consumer contains:
data.email
Guardian can report:
Potentially affected consumer:
response field "email" is used for GET /api/v1/customers
Consumer analysis is intentionally conservative.
A consumer warning represents potential impact, not guaranteed runtime failure.
VS Code Problems Integration
Detected changes are reported through the VS Code Diagnostics API.
Example findings include:
Error Response field "email" was removed from GET /api/v1/customers
Warning Response field "id" changed type from number to string
Warning Potentially affected consumer: response field "email"
This allows developers to inspect API compatibility issues alongside other development problems.
Example: Python

Example: JavaScript / TypeScript

Language Support
API Detection
Supported:
- JavaScript
- TypeScript
- Python (supported FastAPI and Flask patterns; static analysis)
Consumer Analysis
Supported:
- JavaScript
- JSX
- TypeScript
- TSX
The language-specific parsing layer is separated from the core contract comparison engine.
Project Structure
The project separates repository discovery, language analysis, contract comparison, and VS Code integration.
src/
│
├── core/
│ ├── API Contract Models
│ ├── Git Integration
│ ├── Contract Loading
│ ├── Contract Comparison
│ ├── API Discovery
│ └── Consumer Analysis
│
├── languages/
│ └── javascript/
│ ├── Parser
│ ├── Route Detection
│ ├── Response Extraction
│ ├── Module Indexing
│ ├── Module Resolution
│ ├── Mount Detection
│ └── Route Composition
│
├── vscode/
│ └── Diagnostics
│
└── test/
├── Unit Tests
├── Integration Tests
└── E2E Tests
Design Principles
Static analysis
Guardian analyzes source code rather than executing the API.
Git-aware comparison
Previous API contracts are derived from Git revisions.
Repository-wide discovery
API relationships can span multiple files and directories.
No fixed variable names
Guardian does not require Express objects to be named app, router, or another predefined name.
Separation of concerns
The core contract engine is independent from the VS Code diagnostics layer.
Conservative analysis
Potential consumer impact is reported as a warning rather than being presented as a guaranteed runtime failure.
Current Limitations
API Contract Guardian analyzes statically detectable JavaScript, TypeScript, and supported Python API patterns.
Current limitations include:
- Python support is limited to supported FastAPI and Flask patterns
- Primarily Express-style API detection for JavaScript and TypeScript
- Static analysis rather than runtime execution
- Dynamic route construction may not be resolvable
- Dynamic response objects may not be fully inferable
- Complex cross-file data flow may not be resolved
- Arbitrary HTTP clients may not be recognized
- Framework-specific routing outside supported patterns may not be detected
- Dynamic URLs may not be associated with a specific API endpoint
- Complex runtime-generated modules may not be resolvable
For example, a dynamically constructed URL or response object may not provide enough static information for Guardian to determine the complete API contract.
These limitations are intentional: Guardian prioritizes reliable, statically supported findings over speculative analysis.
Testing
The project includes multiple levels of testing.
Unit Tests
Individual components such as:
- Route detection
- Response extraction
- Contract comparison
- Module resolution
- Consumer parsing
- Mount detection
- Route composition
Integration Tests
Interactions between:
- Git revision loading
- Repository discovery
- Module indexing
- Import resolution
- Express detection
- Route composition
- Contract extraction
- Contract comparison
End-to-End Tests
The complete extension workflow, including:
- Git-based scanning
- Added API files
- Modified API files
- Deleted API files
- Cross-file routing
- Nested router composition
- Consumer analysis
- VS Code diagnostics
- Cross-platform source-file handling
Run the test suite with:
npm test
Quick Start
Prerequisites
Clone
git clone https://github.com/komallsingh/api-contract-guardian.git
cd api-contract-guardian
Install dependencies
npm install
Compile
npm run compile
Run tests
npm test
Type checking
npm run check-types
Linting
npm run lint
Installing the VSIX
Package the extension with:
npx @vscode/vsce package
For the current manifest version, this generates:
api-contract-guardian-3.0.0.vsix
Install it from VS Code:
Extensions
→ ...
→ Install from VSIX...
→ api-contract-guardian-3.0.0.vsix
Running a Scan
- Open a Git repository containing a supported JavaScript, TypeScript, or Python API.
- Open the VS Code Command Palette.
- Run:
API Contract Guardian: Scan
- Enter the Git revision to compare against, such as:
HEAD~1
- Open the Problems panel to inspect detected contract changes.
Development
Install dependencies:
npm install
Run type checking:
npm run check-types
Run linting:
npm run lint
Run tests:
npm test
Compile the extension:
npm run compile
Package the extension:
npx @vscode/vsce package
Releases
v3.0.0
Python Route Discovery
- Static route discovery for supported FastAPI and Flask patterns
- Repository-aware route composition across related Python files
- Git-based Python API contract comparison
- Python API findings in VS Code diagnostics
v2.0.0
Repository-Wide API Discovery
Major improvements:
- Repository-wide JavaScript/TypeScript discovery
- Cross-file module indexing
- Import/export resolution
- Express application detection
- Express router detection
- Router mount detection
- Nested router composition
- Multiple router mounts
- Final composed API paths
- Repository-wide API contract discovery
- Git revision comparison
- Consumer impact analysis
- Improved VS Code diagnostics
v1.0.0
Core API Contract Detection
Initial capabilities:
- API endpoint detection
- Response contract extraction
- Removed response field detection
- Response field type comparison
- Consumer impact analysis
- Git-based comparison
- VS Code Problems integration
Roadmap
V1
Core API contract detection.
Status: Complete
V2
Repository-wide JavaScript/TypeScript discovery.
Status: Complete
Includes:
- Cross-file routing
- Module resolution
- Express router composition
- Repository-wide API discovery
- Git-aware comparison
V3
Status: Complete
Python route discovery supports common FastAPI router and Flask blueprint patterns through static analysis. Additional language support remains planned:
Python discovery is static and syntax-pattern based; it does not execute applications or support all Python syntax and framework patterns.
Contributing
Contributions, bug reports, suggestions, and feature requests are welcome.
Development workflow
Create a feature branch:
git checkout -b feature/your-feature
Install dependencies:
npm install
Make the required changes and add tests for new behavior.
Before opening a Pull Request, run:
npm test
npm run lint
npm run check-types
Commit your changes:
git commit -m "Add your feature"
Push your branch:
git push origin feature/your-feature
Then open a Pull Request.
Tech Stack
| Category |
Technology |
| Language |
TypeScript |
| API Analysis |
JavaScript, TypeScript, Python |
| Static Analysis |
AST-based parsing |
| API Framework |
Express, FastAPI, Flask patterns |
| Consumer Analysis |
JavaScript, JSX, TypeScript, TSX |
| Editor Integration |
VS Code Extension API |
| Version Control |
Git |
| Runtime |
Node.js |
| Testing |
Unit, Integration, E2E |
| Packaging |
VSIX |
License
This project is licensed under the MIT License.
See LICENSE for details.
Author
Komal Singh
Software Developer · Backend Developer · Open Source Contributor
API Contract Guardian
Catch breaking API changes before they reach consumers.
⭐ If you find the project useful, consider starring the repository.