Agent Wranglers

MOB-13Required

Keep old app versions working against the API

Every app version you still support works against every API release. A server change never breaks a supported build that people have not updated.

By Agent Wranglers. Updated .

How to do it

People update late or never, so a web-style deploy that changes a response breaks their app. Send the app version and platform in a header on every call, such as App-Version: ios/3.4.0. Add fields instead of renaming or removing them, as version only for breaking changes says. Keep a contract test suite for the oldest supported build and run it against each API release. Remove an old field only after usage by supported versions drops to zero in the logs. Then retire versions with stop versions you no longer support.

Examples

TypeScript example

app.use((req, res, next) => {
  const [platform, version] = (req.get('App-Version') ?? '').split('/');
  req.appClient = { platform, version };
  metrics.increment('api.requests', { platform, version });
  next();
});

Kotlin example

class AppVersionHeader : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response =
        chain.proceed(chain.request().newBuilder()
            .header("App-Version", "android/${BuildConfig.VERSION_NAME}")
            .build())
}

How to check

CI runs the contract tests of the oldest supported app version against every API change, and a failure blocks the deploy. Logs show every API request carries the app version header.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/mobile-apps/updates-and-versions/old-versions-keep-working">Agent Wranglers mobile apps playbook</a>. In code you write, add a comment next to it with the same link.