API Versioning Strategies and Compatibility Practices in a Mobile App Store Backend

The author, who previously led server development for the Vivo app store, recounts how the service grew from millions to tens of millions of daily active users and had to evolve from a monolith to a micro‑service cluster to support rapid client iteration.

Three generic API versioning approaches are examined: (1) The Knot – a single ever‑changing API requiring all clients to upgrade; (2) Point‑to‑Point – each client version accesses a dedicated API; and (3) Compatible Versioning – a single API that remains backward compatible while newer features are added.

Real‑world challenges emerged as the product diversified: multiple client versions, frequent UI changes, legacy architecture with high maintenance cost, and the need to upgrade protocols and split services for high‑traffic modules such as home page, detail, and download.

The migration was carried out in two phases: Phase 1 introduced a new JSON protocol for new interfaces while keeping old interfaces compatible via version checks; Phase 2 completed a full protocol upgrade, refactored the backend framework, and split out high‑load services and internal RPC utilities for historical versions.

Compatible Versioning is further broken down into concrete tactics: API version numbers in URLs or headers, client‑side version checks encapsulated in resource objects to avoid scattered if‑else logic, and feature‑flag fields using bit‑mask integers to signal supported capabilities without tight coupling to version numbers.

Additional interface design advice emphasizes scenario‑aware endpoints (e.g., /app/{scene}/upgrade), proper authentication and service isolation to handle both consumer‑side and system‑side callers, and the importance of logging and monitoring for rapid issue diagnosis.

The author concludes that no single solution fits all cases; the goal is to choose the most suitable, extensible design, noting emerging cross‑platform technologies like Flutter and Weex that can reduce client release frequency and backend compatibility burden.

References: 1) "The Costs of Versioning an API"; 2) Agile development – train release model.