Metadata-Version: 2.4
Name: apidiffx
Version: 0.1.0
Summary: Git diff for API behavior: capture, compare, and classify JSON API changes.
Author: API Diff X Contributors
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# API Diff X

**Git diff for API behavior.**

`apidiffx` captures API responses, compares snapshots, detects structural changes, classifies breaking changes, and provides CI-friendly exit codes.

## Install

```bash
python -m pip install -e .
```

## Capture

```bash
apidiffx capture https://example.com/api/users --output baseline.json
```

## Compare

```bash
apidiffx compare baseline.json current.json
```

JSON report:

```bash
apidiffx compare baseline.json current.json --format json
```

A breaking change returns exit code `1`; otherwise `0`.

## Python

```python
from apidiffx import compare

result = compare("baseline.json", "current.json")

print(result.has_breaking_changes)
for change in result.changes:
    print(change.path, change.change_type, change.severity)
```

## What v0.1 detects

- Added JSON fields
- Removed JSON fields
- Nested object changes
- Array element changes
- Type changes
- HTTP method and URL changes
- HTTP success-to-error status changes
- Header additions/removals
- Sensitive-data masking
- Text and JSON reports
- CI-friendly exit codes

## Project direction

The long-term goal is to make API compatibility work like a Git diff:

```text
old API behavior
       ↓
   apidiffx
       ↓
new API behavior
       ↓
structural diff
       ↓
breaking-change analysis
```

## Development

```bash
python -m pip install -e .
python -m pytest -q
```

## License

MIT


## OpenAPI / Swagger contract diff

Compare two OpenAPI documents:

```bash
apidiffx openapi old.json new.json
```

JSON output:

```bash
apidiffx openapi old.yaml new.yaml --format json
```

YAML support is optional:

```bash
python -m pip install -e ".[yaml]"
```

The OpenAPI diff currently detects:

- Removed endpoints
- Added endpoints
- Removed operations
- Added operations
- Removed response definitions
- Added response definitions
- Removed response properties
- Added response properties
- Required properties added/removed
- Parameter additions/removals
- Parameters becoming required
- Schema type changes
- Array item schema changes
- Selected enum/format/pattern changes

## pytest integration

Install development/test dependencies:

```bash
python -m pip install -e ".[dev]"
```

Use the compatibility assertion directly:

```python
from apidiffx import assert_compatible


def test_users_api(client):
    response = client.get("/api/users")
    assert_compatible(response, "snapshots/users.json")
```

For a `requests.Response`, `apidiffx` reads the request method, URL, status,
headers, and JSON/text body automatically.

You can also save a refreshed snapshot after a successful comparison:

```python
assert_compatible(
    response,
    "snapshots/users.json",
    snapshot_path="snapshots/users-new.json",
)
```


## Authentication and request configuration

Real-world APIs can be captured with custom headers, Bearer tokens, API keys,
query parameters, and request bodies.

Examples:

```bash
apidiffx capture https://api.example.com/users \
  --header "Accept=application/json" \
  --bearer-token "${API_TOKEN}" \
  --output baseline.json
```

API key:

```bash
apidiffx capture https://api.example.com/users \
  --api-key "${API_KEY}" \
  --api-key-header "X-API-Key"
```

Query parameters:

```bash
apidiffx capture https://api.example.com/users \
  --param "page=1" \
  --param "limit=20"
```

POST JSON:

```bash
apidiffx capture https://api.example.com/users \
  --method POST \
  --header "Content-Type=application/json" \
  --json '{"name":"John","email":"john@example.com"}'
```

Basic authentication:

```bash
apidiffx capture https://api.example.com/users \
  --basic-user "${API_USER}" \
  --basic-password "${API_PASSWORD}"
```

Environment variables use the `${VARIABLE}` syntax. Values are resolved from
the process environment, and sensitive response fields are masked before the
snapshot is written.
## Multi-endpoint configuration

Create `apidiffx.yaml`:

```yaml
name: patient-api
base_url: https://api.example.com
headers:
  Accept: application/json
auth:
  type: bearer
  token: ${API_TOKEN}
endpoints:
  - name: users
    method: GET
    path: /users
  - name: patient
    method: GET
    path: /patients/123
    params:
      include_history: true
  - name: create_user
    method: POST
    path: /users
    json:
      name: John
      email: ${TEST_EMAIL}
```

Install YAML support:

```bash
pip install "apidiffx[yaml]"
```

Then create/update all baselines:

```bash
apidiffx update
```

Run the complete compatibility test:

```bash
apidiffx test
```

`apidiffx test` checks every configured endpoint and exits with code `1` when a breaking response change is detected, making it suitable for CI/CD. Environment variables can be referenced with `${VAR_NAME}` so credentials do not need to be committed to the configuration file.

### Endpoint inventory changes

When you run `apidiffx update`, API Diff X also records the configured endpoint inventory in `.apidiffx/manifest.json`. On later `apidiffx test` runs it can detect contract-level inventory changes:

- **Removed endpoint** — breaking
- **Changed method/path for an existing endpoint** — breaking
- **Added endpoint** — non-breaking
- **Renamed configuration entry with the same method/path** — non-breaking; the existing response baseline is reused

This keeps endpoint changes separate from response-body diffs and avoids noisy field-level differences when an endpoint itself has moved.


## CI and HTML reports

`apidiffx test` is CI-friendly: it exits with code `1` when configured breaking changes are detected and `2` when a baseline/configuration is missing or invalid.

Generate a standalone HTML report:

```bash
apidiffx test --report apidiffx-report.html
```

The report contains endpoint status, change counts, breaking changes, and detailed field-level differences. A GitHub Actions example is included at `.github/workflows/apidiffx.yml`.

For JSON output suitable for other CI systems:

```bash
apidiffx test --format json --report apidiffx-report.json
```
