Skip to Content

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.

  • apiCompatibilityLevel goes up by 1 when a change breaks compatibility in either direction.
  • minClientApiCompatibilityLevel is the oldest app this server serves.
  • minServerApiCompatibilityLevel is 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.

  1. 1Is the app's level below the server's minClientApiCompatibilityLevel?
    Yes
    Update OpenBeaconThe server answers 426 CLIENT_TOO_OLD.
    No
  2. 2Is the server's level below the app's minServerApiCompatibilityLevel?
    Yes
    Your server needs updatingOn our hosted server the app says "We're updating OpenBeacon".
    No
  3. 3Did the app call a procedure the server doesn't have?
    Yes
    The app and server don't matchThe server answers 404 UNKNOWN_PROCEDURE.
    No
  4. None of these
    Compatible
What the app decides from the levels

When to change a level

Change a level only if one of these is true:

  1. 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. Raise apiCompatibilityLevel and set minServerApiCompatibilityLevel to it.
  2. 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 apiCompatibilityLevel and set minClientApiCompatibilityLevel to it.
  3. You changed an encrypted format or what a field means. A new file in packages/encryption/src/testVectors is 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 minClientApiCompatibilityLevel is 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 minClientApiCompatibilityLevel locks 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 /health returns apiCompatibilityLevel and minClientApiCompatibilityLevel with status, version and serverName. It can also carry message and announcements.
  • Every request to /api/* sends x-openbeacon-api-compatibility-level. A missing or unreadable value counts as 0. The exception is GET /api/auth/google-deletion-callback, which a browser opens.
  • Every /api/* response carries x-openbeacon-api-compatibility-level and x-openbeacon-min-client-api-compatibility-level.
  • An app below the minimum gets a 426 with { "code": "CLIENT_TOO_OLD", "minClientApiCompatibilityLevel": number, "message"?: string }, except on GET /api/auth/get-session and POST /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.
  • message is plain text of at most 280 characters, from the server's CLIENT_UPDATE_MESSAGE. The app shows it on every compatibility screen.
  • announcements is 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 /health at 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 /health at 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

LevelChange
1Compatibility levels introduced.
2Multi-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.
3Phone and tablet variants and general icons for devices. Both minimums 3.
4Pausing location sharing for a device or the whole account. Both minimums 4. The Beta 1 baseline.
5Invite previews, shown before anyone joins. Server minimum 5. Client minimum stays 4.
6Places, Place Sharing and Place Transitions. Server minimum 6. Client minimum stays 4.
7Group history. Join alerts removed. Both minimums 7.
8account.viewers, for the Who can see me screen. Server minimum 8. Client minimum stays 7.
9Profile and group pictures encrypted end to end, with new upload steps. Both minimums 9. The migration clears every picture stored before it.
10Tracking point v2, a 23-byte binary format, and new point storage. Both minimums 10. The migration deletes stored history and live-map points.
11Notification settings, group activity notices on phones, Account Notices and Push wake-ups. Server minimum 11. Client minimum stays 10.
12Sign-in codes. Both minimums 12.
13Location 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.
14Leaving 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.
15Google 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.

On this page