Skip to main content

Changes

Non-Breaking Change​

A non-breaking change is any update to the API that does not require existing clients to change their behavior or implementation. Existing clients continue to work as expected.

Example of Non-Breaking Change​

ScenarioWhy It's Non-Breaking
Adding a new optional fieldClients can ignore fields they don't recognize.
Adding a new endpointClients using old endpoints remain unaffected.
Extending enum valuesClients can default to ignoring unknown values.
Increasing a limit (e.g., pagination)Clients using previous limits still function.

Example: Adding a New Field​

Old Response:

{
  "id": 1,
  "name": "Alice"
}

New Response(Non-Breaking)

{
  "id": 1,
  "name": "Alice",
  "nickname": "Ally"
}

Why it's non-breaking: Existing clients that don't expect nickname will simply ignore it.

Breaking Change​

A breaking change is any modification that requires existing clients to change their code in order to continue functioning properly.

Example of Breaking Changes​

ScenarioWhy It's Breaking
Removing an existing fieldClients depending on it may break.
Renaming a fieldClient parsing will fail.
Changing a field’s data typeData may be incompatible.
Changing URL structure or HTTP methodsClients using hardcoded URLs/methods will break.
Changing authentication mechanismClients using the old auth method fail.

Example: Renaming a Field​

Old Response:

{
  "id": 1,
  "name": "Alice"
}

New Response(Breaking)

{
  "id": 1,
  "fullName": "Alice"
}

Why it's breaking: Existing clients looking for name will no longer find it and may throw errors.