Versioning
Change your data's shape without breaking anything already using your search.
What a version is
A list's version is the shape it presents to the outside world — which fields exist and what they're called. It's the number in every search URL: /movies/1. Your movies list is still on version 1 despite the plot, genre, year and poster you added.
What does and doesn't bump the version
A change that could break an app already reading your data creates a new version; a change that couldn't, doesn't.
| Change | Safe for existing apps? | New version? |
|---|---|---|
| Add a field | Yes, old apps just ignore it | No |
| Add or edit records | Yes | No |
| Rename a field | No, apps asking for the old name would break | Yes |
| Remove a field | No | Yes |
A breaking change, handled safely
Rename genre to category and the list moves to version 2. Version 1 carries on unchanged:
GET https://api.searchstack.dev/search/Demo/movies/1?query=matrix → still has "genre"
GET https://api.searchstack.dev/search/Demo/movies/2?query=matrix → now has "category"- Upgrade each app to version 2 when you're ready, one at a time.
- A group pins each list at a fixed version, so
movies-and-actorscarries on untouched until you move it forward.
Made a mistake? Restore
Restore rolls the list's shape back to an earlier version and keeps your records — an undo for structure, with no rebuild.
Exactly what bumps a version, pin-and-migrate, and the restore flow: the Versioning reference.
Next: Contributors »
Invite a teammate to help manage a list.