API Versioning Strategies and Backend Architecture Evolution in Vivo App Store

The author, a member of the Vivo Internet Server Team, shares experiences from developing the Vivo App Store backend, which grew from millions to tens of millions of daily active users. The article discusses how the backend architecture evolved from a monolith to a service cluster and micro‑service upgrades while maintaining compatibility with multiple client versions.

General Solutions

Because the App Store client updates frequently, multiple client versions coexist, making forced upgrades undesirable. Three common API versioning approaches are presented:

Solution 1: The Knot (no version) – a single API version that all users must adopt. Solution 2: Point‑to‑Point – APIs carry explicit version numbers, and clients choose which version to use. Solution 3: Compatible Versioning – a single API version that remains backward compatible with previous versions.

Images illustrating these models are included in the original article.

Specific Business Challenges and Exploration

The rapid iteration of the App Store introduced several challenges:

Supporting multiple client versions and a PC assistant simultaneously.

Frequent interface changes due to diverse product forms.

Legacy monolithic architecture with high maintenance cost, requiring protocol upgrades and service splitting.

The backend transformation proceeded in two stages:

New interfaces adopted a new JSON protocol, while existing interfaces added compatibility logic based on client version.

After completing protocol upgrades for all new versions, the backend architecture was refactored to improve stability, performance, and maintainability. High‑traffic services (home page, detail page, download) were split into independent services, and common internal RPC services (e.g., app detail retrieval, filtering) were extracted.

Resulting architecture separates “Old‑Service” (maintained for legacy clients using Point‑to‑Point) from newer services that follow The Knot model, emphasizing careful backward‑compatible upgrades.

Compatible Versioning Details

Common strategies include API version numbers, client version numbers, and feature‑flag parameters.

Scenario 1: API Version Control

Adding a version segment to the URL (e.g., /{version}/index) or using request‑header version parameters allows clean separation of logic per version, reducing complex conditional code.

Scenario 2: Client Version Control

Embedding client version information in resource objects enables unified filtering logic, avoiding scattered if‑else checks. A utility class can encapsulate this filtering, and a higher‑level resource class can provide a common interface for all resources.

Scenario 3: Feature Flag Parameters

Introducing an integer‑based flag field allows the server to evaluate capabilities via bitwise operations, decoupling feature availability from strict client version numbers.

Further Reflections on Interface Design

Key considerations include:

Scenario awareness : Include scenario identifiers in API paths (e.g., /app/{scene}/upgrade) to aid traffic analysis and debugging.

Authentication and Service Isolation : Properly record, authenticate, and isolate calls, especially when interfaces serve both client apps and system applications, to prevent overload.

The article concludes with a brief look at emerging cross‑platform technologies (Flutter, Weex) that can reduce client release frequency and backend compatibility work, emphasizing that the best solution is the one that fits the business context.

References

1. The Costs of Versioning an API

2. Agile Development – Train Release Model