API Contract Guard

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

Installation

pip install api-contract-guard

Python usage

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

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

Fail a CI job when a breaking change is detected:

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

JSON output:

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

Ignore dynamic fields:

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

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