Metadata-Version: 2.4
Name: api-contract-guard
Version: 0.2.0
Summary: Detect breaking changes between JSON API responses
Author: Venna Venkatasivaramireddy
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"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Dynamic: license-file

# API Contract Guard

[![PyPI version](https://img.shields.io/pypi/v/api-contract-guard.svg)](https://pypi.org/project/api-contract-guard/)
[![Python versions](https://img.shields.io/pypi/pyversions/api-contract-guard.svg)](https://pypi.org/project/api-contract-guard/)
[![Tests](https://github.com/venkatasivaramireddy/api-contract-guard/actions/workflows/test.yml/badge.svg)](https://github.com/venkatasivaramireddy/api-contract-guard/actions/workflows/test.yml)
[![License](https://img.shields.io/pypi/l/api-contract-guard.svg)](LICENSE)

`api-contract-guard` detects breaking changes between an approved API contract and a new response. It supports raw JSON response comparison, OpenAPI/Swagger response-schema comparison, wildcard ignore rules, machine-readable JSON reports, HTML reports, coloured terminal output, and CI-friendly exit codes.

## Installation

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

Python 3.10 or newer is required.

## Quick start

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

Example output:

```text
3 breaking change(s), 2 non-breaking change(s)
------------------------------------------------------
REMOVED       id (was "123")
REMOVED       isSelected (was true)
REMOVED       portNumber (was 104)
ADDED         port = "104"
ADDED         uuid = "123"
```

Fail a build when breaking changes are detected:

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

## 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:
    print("The new response breaks the approved contract")
```

## Report formats

### JSON report

```bash
api-contract-guard expected.json actual.json \
  --format json \
  --output contract-report.json
```

The report includes a summary and a structured list of changes:

```json
{
  "summary": {
    "total": 1,
    "breaking": 1,
    "non_breaking": 0
  },
  "changes": [
    {
      "path": "patient.id",
      "kind": "removed",
      "expected": "123",
      "actual": null,
      "breaking": true
    }
  ]
}
```

### HTML report

```bash
api-contract-guard expected.json actual.json \
  --format html \
  --output contract-report.html
```

Open `contract-report.html` in a browser to view a readable, shareable report.

## Wildcard ignore rules

Dynamic values such as timestamps, IDs, request tokens, and list-item metadata can be ignored.

Ignore one path:

```bash
api-contract-guard expected.json actual.json --ignore modified_at
```

Ignore the same field in every list item:

```bash
api-contract-guard expected.json actual.json \
  --ignore 'users[*].updated_at'
```

Multiple ignore rules can be supplied:

```bash
api-contract-guard expected.json actual.json \
  --ignore request_id \
  --ignore 'users[*].updated_at' \
  --ignore 'items.*.trace_id'
```

## OpenAPI and Swagger comparison

Compare response schemas in OpenAPI 3.x or Swagger 2.x JSON documents:

```bash
api-contract-guard old-openapi.json new-openapi.json \
  --mode openapi \
  --fail-on-breaking
```

The OpenAPI comparator reports:

- removed operations or response status codes
- added operations or response status codes
- removed schema properties
- changed schema types
- changed required-property lists and other schema values
- local `$ref` response/schema targets

Current OpenAPI support focuses on response contracts. Request bodies, parameters, security schemes, and YAML input are planned for later releases.

## Comparison options

```text
--strict-additions      Treat newly added fields as breaking
--check-values          Report scalar value changes
--check-list-length     Treat list-length changes as breaking
--ignore PATH           Ignore a path; repeatable and wildcard-aware
--mode json|openapi     Select JSON response or OpenAPI comparison
--format text|json|html Select output format
--output FILE           Write the report to a file
--no-colour             Disable terminal colours
--fail-on-breaking      Exit with code 1 for breaking changes
```

## Exit codes

| Exit code | Meaning |
|---|---|
| `0` | Comparison completed |
| `1` | Breaking changes found with `--fail-on-breaking` |
| `2` | Invalid input, missing file, or malformed JSON |

## CI integration

A full GitHub Actions example is available in [`docs/CI_USAGE.md`](docs/CI_USAGE.md). A ready-to-adapt workflow is also included at `.github/workflows/contract-check-example.yml`.

Minimal example:

```yaml
- run: pip install api-contract-guard
- run: api-contract-guard expected.json actual.json --fail-on-breaking
```

## Development

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

Build and validate a release:

```bash
rm -rf build dist src/*.egg-info
python -m build
python -m twine check dist/*
```

## Release notes

See [CHANGELOG.md](CHANGELOG.md).

## Contributing

Bug reports and focused pull requests are welcome. Please include tests for behavioural changes and run `pytest` and `ruff check .` before submitting a pull request.

## Licence

MIT
