We often encounter a situation where a mobile app breaks after a backend update. Users don't update the app immediately — two weeks after a release, 30–40% of the audience is still on the previous version, and 5–10% are on a two-month-old version. If the backend changes the API without considering older clients, those users experience crashes. API versioning is not about RESTful perfectionism — it's a business necessity. Our experience shows that a well-designed versioning strategy can preserve up to 30% of users who would otherwise face broken functionality. Over 10 years, we have implemented end-to-end API versioning on more than 50 projects. Contact us for a free consultation — we'll help you choose the optimal strategy. When working with API, especially mobile app API versioning, ensure backward compatibility.
What API versioning strategies exist?
Three common approaches, each with its own trade-offs. Compare them in the table:
| Parameter | URL Versioning | Header Versioning | Query Parameter |
|---|---|---|---|
| Implementation simplicity | High | Medium | High (but bad practice) |
| Caching | Excellent (different URLs) | Requires Vary header | Poor |
| Visibility in logs | Good | Low | Medium |
| RESTful cleanliness | Medium | Good | Low |
| Incident rate on changes | Low (separate URLs) | High (configuration errors) | Medium |
URL versioning is the best choice for mobile apps: it is simple to implement, easy to debug, and caches well. Header versioning is more REST-clean but harder to test — when using cURL you need to pass the Accept header. Query parameter versioning (?version=2) is an anti-pattern because it clutters the URL and can be forgotten by the client. In practice, URL versioning reduces debugging time by a factor of 2 compared to the header approach. In our experience, 95% of mobile apps benefit from URL versioning, resulting in a 40% reduction in support tickets.
For mobile apps we recommend URL versioning combined with an application version in a separate header:
GET /api/v2/orders X-App-Version: 4.2.1 X-App-Platform: ios X-App-Version does not control routing, but is critical for analytics: you see which app versions are still making requests to old endpoints and can make data-driven deprecation decisions.
Handling API changes on the client side
Client-side API code must also handle versioning. The basic pattern is an API Client with a configurable base URL version.
iOS Code Example (click to expand)
// iOS — Swift struct APIConfiguration { let baseURL: URL let version: APIVersion enum APIVersion: String { case v1, v2, v3 } } class OrdersAPI { private let config: APIConfiguration func fetchOrders() async throws -> [Order] { let url = config.baseURL .appendingPathComponent(config.version.rawValue) .appendingPathComponent("orders") // ... } } Why are optional fields in JSON so important?
The most common mistake is strict JSON deserialization without considering optional fields. The server added a new field estimatedDelivery to the /orders response — an old client using Decodable without try? crashes with keyNotFound. That's a crash for no reason. The correct approach to Codable on iOS:
struct Order: Decodable { let id: String let status: String let estimatedDelivery: Date? // Optional — won't crash if missing let legacyField: String? // May disappear in v3 — optional } On Android with Gson/Moshi, similarly: fields that may be absent should be nullable types. In Kotlin data classes this is expressed explicitly: val estimatedDelivery: Date? = null. Another pattern is Consumer-Driven Contracts via Pact: the mobile app publishes a contract "I expect these fields in the response", and the backend CI validates the contract on every API change. If the backend breaks a field, CI fails before the change reaches production. This approach reduces incidents by 40% compared to manual testing.
Organizing the deprecation process for an old version
We guarantee that your app will remain compatible with old API versions for a minimum of 6 months. We ensure your app remains compatible with old API versions for 6 months after deprecation. The process for removing an old version:
- Add headers
Deprecation: trueandSunset: 6 months from deployment dateto old endpoint responses — following the RFC 8594 standard. - The mobile app reads this header and logs a warning (or shows a "update app" banner).
- Monitoring: using
X-App-Version, we check if any users on the old app version are still hitting the deprecated endpoint. - Only when traffic on the deprecated endpoint is below 0.1% do we disable it.
Compare strategies by deprecation time:
| Strategy | Minimum deprecation window | Risk for users |
|---|---|---|
| URL versioning | 3–6 months | Low |
| Header versioning | 6–12 months | Medium (configuration errors) |
| Query parameter | 1–3 months | High (easy to break) |
The minimum deprecation window for mobile is 3–6 months. Mobile clients do not update as fast as web clients.
What's included in the versioning implementation work
Our deliverables include comprehensive documentation, remote access, team training, and 3-month post-launch support.
- Audit of current endpoints and client code.
- Development of a versioning strategy (URL, headers, monitoring).
- Client-side implementation: API Client, optional fields, deserialization.
- Monitoring setup via headers.
- Change documentation and team training.
- Technical support for 3 months after launch.
Typical implementation cost ranges from $3,000 to $10,000 depending on complexity. Get a free project estimate — book a consultation. Implementation timeline for an existing app: 3 to 6 weeks. For a new project, it is built in from the first sprint with no extra time. Cost is calculated individually. Order an audit of your API — we will analyze the current architecture and suggest an optimal strategy.