breaking-changes

# breaking-changes

Reference guide for how api-diff-checker classifies changes as breaking or non-breaking.

## Breaking change rules

A change is classified as **breaking** if it can cause existing clients to fail without modification:

| Change | Why it breaks |
|--------|---------------|
| Endpoint removed | Existing clients calling it will get 404 |
| Required parameter added | Existing calls without that parameter will fail with 400 |
| Parameter type narrowed (e.g. string -> integer) | Existing values may not match new type |
| Request body made required | Existing calls without a body will fail |
| Response status code removed | Clients handling that status will be confused |
| Response schema field removed | Clients reading that field will get undefined |
| Response schema field type changed | Clients parsing that type will fail |
| Security scheme added | Unauthenticated clients will get 401 |

## Non-breaking changes

A change is **non-breaking** if existing clients continue to work unchanged:

| Change | Why it is safe |
|--------|----------------|
| Endpoint added | New surface, no existing client uses it |
| Optional parameter added | Existing calls still work without it |
| Required parameter made optional | Relaxing a constraint |
| Optional response field added | Existing clients ignore unknown fields |
| Security scheme removed | Auth relaxed, existing clients still work |

## Informational (no impact)

These changes do not affect behavior:

| Change | Notes |
|--------|-------|
| Description changed | Documentation only |
| Title changed | Documentation only |
| Example values changed | Not part of runtime behavior |

## Checking a specific change

```bash
# Diff two specs and filter to breaking only
adc diff api-v1.yaml api-v2.yaml --only-breaking --format json | jq '.changes[]'

# Check if a particular endpoint changed
adc diff api-v1.yaml api-v2.yaml --format json | \
  jq '[.changes[] | select(.path | contains("users"))]'
```

## API response - checking programmatically

```javascript
const result = await fetch('/api/diff', { method: 'POST', body: form });
const diff = await result.json();

if (diff.summary.breaking > 0) {
  console.error('Breaking changes detected:', diff.summary.breaking);
  process.exit(1);
}
```

## Common questions

**Q: Is changing a response field from required to optional breaking?**
No. Clients that always check for the field will still work. Non-breaking.

**Q: Is changing an enum to add a new value breaking?**
Clients that use exhaustive enum matching may break. Classified as breaking.

**Q: Is renaming an endpoint breaking?**
Yes - the old endpoint is removed and a new one is added. The removal is breaking.

**Q: Is adding a new security scheme breaking?**
Yes - existing clients that do not send auth credentials will receive 401.