API compatibility
How the app and the server tell when the other is too old, and when to change the levels.
The app and the server can be on different versions. Self-hosters update their server when they choose, and people update the app when they choose. API compatibility levels let each side tell when the other is too old, so the app can show a clear screen instead of failing in confusing ways. See App and server versions for what people see.
The three numbers
They live in packages/shared/src/apiCompatibilityLevel.ts. The app and the server each build their own copy.
apiCompatibilityLevelgoes up by 1 when a change breaks compatibility in either direction.minClientApiCompatibilityLevelis the oldest app this server serves.minServerApiCompatibilityLevelis the oldest server this app works with.
oldestSupportedAppVersion in apps/backend/src/version.ts is the oldest app version this server accepts: the first release on minClientApiCompatibilityLevel. The backend logs it at startup so self-hosters can see which apps it serves. Whenever minClientApiCompatibilityLevel goes up, update it: to the new expo.version for a brand-new level, otherwise to the first app version that reached that level.
The app is too old when its apiCompatibilityLevel is below the server's minClientApiCompatibilityLevel. The server is too old when its apiCompatibilityLevel is below the app's minServerApiCompatibilityLevel. Both minimums are always at most apiCompatibilityLevel, so both can't be true at once.
Apps talk to other apps through the server, so the client minimum also covers changes between apps. If older apps can't read a new encrypted format, raising minClientApiCompatibilityLevel makes everyone update.
- 1Is the app's level below the server's minClientApiCompatibilityLevel?YesUpdate OpenBeaconThe server answers 426 CLIENT_TOO_OLD.No
- 2Is the server's level below the app's minServerApiCompatibilityLevel?YesYour server needs updatingOn our hosted server the app says "We're updating OpenBeacon".No
- 3Did the app call a procedure the server doesn't have?YesThe app and server don't matchThe server answers 404 UNKNOWN_PROCEDURE.No
- None of theseCompatible
When to change a level
Change a level only if one of these is true:
- The app now relies on something older servers don't have. A new procedure, a new input field on a procedure whose schema rejects unknown keys (
z.strictObject), or a new input field the app needs the server to act on. Most input schemas are loose, so an older server silently drops a field it doesn't know. RaiseapiCompatibilityLeveland setminServerApiCompatibilityLevelto it. - You removed or narrowed something a supported app relies on. A procedure, a required input, a tighter validation rule, or an output field the app reads. Prefer not to. If you must, raise
apiCompatibilityLeveland setminClientApiCompatibilityLevelto it. - You changed an encrypted format or what a field means. A new file in
packages/encryption/src/testVectorsis a sign of this. Raise the minimum for whichever side can't cope.
Anything else needs no change, including a new procedure the app doesn't call yet, a new optional input that an older server can safely ignore, a new output field, looser validation, refactors, and migrations that keep the API the same.
scripts/check-version-bump.ts checks that levels never go down, apiCompatibilityLevel goes up by at most 1, neither minimum is above it, and any level change comes with at least a minor bump of both the app and the server. It also checks that oldestSupportedAppVersion never goes down or above the app's expo.version, stays the same unless minClientApiCompatibilityLevel changes, equals the new expo.version when the minimum rises to a brand-new level, and goes up when the minimum rises to an existing level. It can't tell whether a change needed a new level; that's for you and your reviewer.
Every pull request body says either API compatibility: unchanged or API compatibility: raised because …. The pull request template has the line.
Prefer additive changes
- Keep old procedures and fields working, and add new ones alongside them.
- Retire old API in its own pull request, once we decide to stop supporting the apps that use it. Only remove it once
minClientApiCompatibilityLevelis above the newest app that called it. - Release the server before an app that raises
minServerApiCompatibilityLevel, so the app doesn't arrive before a server that supports it. - Raising
minClientApiCompatibilityLevellocks out everyone on an older app until they update. Give store updates time to reach people first.
The handshake never changes
Tests in apps/backend/src/app.test.ts pin these against literal strings:
GET /healthreturnsapiCompatibilityLevelandminClientApiCompatibilityLevelwithstatus,versionandserverName. It can also carrymessageandannouncements.- Every request to
/api/*sendsx-openbeacon-api-compatibility-level. A missing or unreadable value counts as 0. The exception isGET /api/auth/google-deletion-callback, which a browser opens. - Every
/api/*response carriesx-openbeacon-api-compatibility-levelandx-openbeacon-min-client-api-compatibility-level. - An app below the minimum gets a 426 with
{ "code": "CLIENT_TOO_OLD", "minClientApiCompatibilityLevel": number, "message"?: string }, except onGET /api/auth/get-sessionandPOST /api/auth/sign-out. Those two always answer, so an app that is too old keeps its session and can sign out. Pausing, leaving a group and deleting the account still need the update. messageis plain text of at most 280 characters, from the server'sCLIENT_UPDATE_MESSAGE. The app shows it on every compatibility screen.announcementsis left out when none are showing. The app drops any entry it can't read.- A call to a procedure the server doesn't have gets a 404 with
{ "code": "UNKNOWN_PROCEDURE", "apiCompatibilityLevel": number }. If the levels match but a procedure is missing, the app shows "The app and server don't match".
A server from before the handshake has no level on /health. The app treats it as level 0, so it's reported as too old.
Error reasons
A rejection the app must act on carries a reason from the ErrorReason union in packages/shared/src/errorReason.ts. It's data.reason on tRPC errors and the Better Auth error code on auth routes. The app reads it with errorReason(error) and never matches on error messages.
Never reuse a reason for a new condition. Add a new reason, which is an additive change. Removing one follows the level rules above.
What the app does
- Checks
/healthat startup and when it comes back to the foreground, and reads the level headers on every response. - Only blocks on a clear answer. Offline, timeouts, server errors and unexpected replies leave things as they are.
- Saves the result per server and app level, so the screen shows straight away next time, even offline.
- Offers Sign out on every screen while someone is signed in, and uses a new server straight away when someone picks Use a different server.
- On Android, pauses background uploads while blocked, checks
/healthat most every 5 minutes, and shows one notification. While the server is too old it keeps recording. While the app is too old or out of sync it stops recording, so nothing is saved for later. - The feedback client sends its level but never changes the app's state, because it always talks to the hosted server.
Level history
| Level | Change |
|---|---|
| 1 | Compatibility levels introduced. |
| 2 | Multi-device accounts: listing, editing, removing and linking devices; new devices wait until they're set up; sessions must be linked to a device. Both minimums 2. |
| 3 | Phone and tablet variants and general icons for devices. Both minimums 3. |
| 4 | Pausing location sharing for a device or the whole account. Both minimums 4. The Beta 1 baseline. |
| 5 | Invite previews, shown before anyone joins. Server minimum 5. Client minimum stays 4. |
| 6 | Places, Place Sharing and Place Transitions. Server minimum 6. Client minimum stays 4. |
| 7 | Group history. Join alerts removed. Both minimums 7. |
| 8 | account.viewers, for the Who can see me screen. Server minimum 8. Client minimum stays 7. |
| 9 | Profile and group pictures encrypted end to end, with new upload steps. Both minimums 9. The migration clears every picture stored before it. |
| 10 | Tracking point v2, a 23-byte binary format, and new point storage. Both minimums 10. The migration deletes stored history and live-map points. |
| 11 | Notification settings, group activity notices on phones, Account Notices and Push wake-ups. Server minimum 11. Client minimum stays 10. |
| 12 | Sign-in codes. Both minimums 12. |
| 13 | Location history reads for Timeline, points filed by the hour they were recorded, and each person's choice of how much history their groups see. Server minimum 13. Client minimum stays 12. |
| 14 | Leaving a group without sending new group keys, colour changes that check the colour the phone last read, recovery phrase changes that check the phrase hasn't changed since, and session checks and sign-out for an app that is too old. Both minimums 14. |
| 15 | Google sign-in tied to the server that asked for it, through a single-use challenge in the token's nonce. Both minimums 15. |
The current level is 15. docs/development/api-compatibility.md lists the procedures each level added.