Versioning
Lists are versioned automatically, so you can change a list’s shape without breaking the apps already using it. The version is part of the address — …/movies/2/inception — and each version keeps serving its own field shape. A deployed client pinned to version 1 goes on getting version 1 for as long as it likes; you move it to version 2 when you are ready, not when the change ships.
A list always shows its current version — here, version 1.
What creates a new version?
Only a breaking change to the shape does. Adding a field or changing your records never bumps the version, because nothing already deployed can break:
| Change | New version? | Why |
|---|---|---|
| Add a field | No | Existing clients simply ignore the extra property. |
| Rename a field | Yes | Clients bound to the old property name would break. |
| Remove a field | Yes | Clients reading the property would receive nothing. |
| Add / edit records | No | Data changes are visible in every version immediately. |
Example
If known_for is renamed to best_movie, version 1 keeps returning known_for while version 2 returns best_movie:
GET /suggest/{account}/actors/1/keanu → { "name": "Keanu Reeves", "known_for": "The Matrix" }
GET /suggest/{account}/actors/2/keanu → { "name": "Keanu Reeves", "best_movie": "The Matrix" }Pin production clients to a specific version and migrate them at your own pace — there is no forced upgrade window.
Restoring a previous version
Changed a list’s shape and want the old one back? You can restore any earlier version. Restore rolls forward, never back: it brings the old version back as a brand-new latest version, so numbers only ever go up and anything already pinned to an older version keeps working. Nothing is overwritten.
It is schema only — your records are never versioned and are left untouched. You are restoring the shape, not the contents.
Auto-plays · use Back / Next to step through at your own pace.
Restore a list
- On the Lists page, open the ⋮ menu on the list’s row and choose Restore Version. (It appears only for lists you own that have earlier versions.)
- Pick the version to bring back and click Restore.
- The list’s version number goes up by one — the old shape is now the newest version, and every earlier version still exists.
Restore a group
Groups restore their membership — which lists, at which versions — rather than a schema. The steps are the same (⋮ menu → Restore Version). If a member list was deleted since that version, it is simply left out and reported, never resurrected as a dead link.
Walk through a rename end-to-end in the Versioning tutorial.