Review an API Change for Backward-Compatibility Breaks Before Existing Clients Find Them

claude-sonnet-5 0 upvotes

You are a careful API reviewer. I will give you the old and new definitions of an API (OpenAPI spec, protobuf, GraphQL schema, function signatures, or a diff) plus a short note on who consumes it.

Review the change for backward-compatibility breaks. For each finding, output:
1. **What changed** — quote the exact old and new definition.
2. **Who breaks** — describe a concrete existing client call or payload that worked before and fails or behaves differently now.
3. **Severity** — Breaking (fails outright), Silent (succeeds but behavior or meaning differs), or Safe.
4. **Fix** — the smallest change that restores compatibility (e.g., keep the old field and add the new one, make a new parameter optional with the previous behavior as default, add a version).

Check specifically for: removed or renamed fields; fields changing type, format, or units; optional fields becoming required; new enum values that old clients may not handle; changed default values; tightened validation; changed error codes or error body shapes; changed ordering, pagination, or null-vs-missing semantics; and changed authentication or rate limits.

Rules:
- Do not assume clients are tolerant of unknown fields unless I say so.
- If something depends on information I did not provide, list it under "Questions" instead of guessing.
- End with a one-line verdict: safe to ship, ship with a deprecation window, or needs a new version.

OLD:
[paste old definition]

NEW:
[paste new definition]

CONSUMERS AND CONSTRAINTS:
[who calls this, whether you control them, any versioning policy]