Metadata-Version: 2.4
Name: api-contract-guard
Version: 0.1.0
Summary: Detect breaking changes between JSON API responses
Author-email: Venna Venkatasivaramireddy <vennavenkat147@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/venkatasivaramireddy/api-contract-guard
Project-URL: Repository, https://github.com/venkatasivaramireddy/api-contract-guard
Project-URL: Issues, https://github.com/venkatasivaramireddy/api-contract-guard/issues
Keywords: api,contract-testing,json,breaking-changes,ci
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Dynamic: license-file

# API Contract Guard

`api-contract-guard` detects breaking changes between an approved JSON API response and a new response.

## Installation

```bash
pip install api-contract-guard
```

## Python usage

```python
from api_contract_guard import compare, to_text

expected = {
    "id": "123",
    "portNumber": 104,
    "isSelected": True,
}

actual = {
    "uuid": "123",
    "port": "104",
}

report = compare(expected, actual)
print(to_text(report))

if report.has_breaking_changes:
    raise SystemExit(1)
```

## CLI usage

```bash
api-contract-guard examples/expected.json examples/actual.json
```

Fail a CI job when a breaking change is detected:

```bash
api-contract-guard \
  examples/expected.json \
  examples/actual.json \
  --fail-on-breaking
```

JSON output:

```bash
api-contract-guard expected.json actual.json --format json
```

Ignore dynamic fields:

```bash
api-contract-guard expected.json actual.json \
  --ignore modified_at \
  --ignore metadata.request_id
```
## integrate with your python code

```
from api_contract_guard import compare, to_text

expected = {
    "id": "123",
    "portNumber": 104,
    "isSelected": True,
    "server": {
        "name": "Primary PACS",
    },
}

actual = {
    "uuid": "123",
    "port": "104",
    "server": {
        "name": "Primary PACS",
    },
}

report = compare(expected, actual)

print(to_text(report))

if report.has_breaking_changes:
    print("API contains breaking changes")
```

## Current comparison rules

- Removed fields are breaking.
- Type changes are breaking.
- Added fields are non-breaking by default.
- Nested dictionaries and list items are compared.
- Dynamic paths can be ignored.
- Value comparison and list-length comparison are optional.

## Development

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e ".[dev]"
pytest
ruff check .
python -m build
python -m twine check dist/*
```

## Licence

MIT
