API contracts & compatibility

Why renaming a database column breaks mobile apps halfway across the world.

The idea

When you build an API, you are establishing a Contract with the client apps (like iOS or Android). If you change the shape of the data, the API might deploy instantly, but old versions of the mobile app are still installed on millions of phones. If they expect a field that is now missing, they crash.

To avoid this, API changes must be Backward Compatible. You cannot rename or delete fields. You can only make Additive Changes: adding new fields, while keeping the old ones alive until you can prove no old clients are using them anymore.

App (v1.0) render() { name = user.name } OK (Reads "name") GET /api/user Server API { "id": 1, "name": "Bob" }
v1.0 App expects a field called "name". It works.

How it works (Additive Changes)

# BAD: Breaking Change
# The backend renames the field to separate first/last name.
# Millions of v1.0 apps crash because user.name is suddenly null!
return {
    "id": 1,
    "first_name": "Bob",
    "last_name": "Smith"
}

# GOOD: Additive Change
# We ADD the new fields, but KEEP the old field populated.
# v1.0 apps keep working. v2.0 apps can use the new fields.
return {
    "id": 1,
    "name": "Bob Smith",       # Legacy (Don't delete!)
    "first_name": "Bob",       # New
    "last_name": "Smith"       # New
}