Apollo iOS Upgrade Proposal: 0.50.0 → 2.0

apollo-ios-upgrade-proposal.md

Apollo iOS Upgrade Proposal: 0.50.0 → 2.0

Current Version: 0.50.0 (released ~2022) Latest Stable: 2.0.6 (February 2025) Recommendation: Upgrade to benefit from Swift concurrency, stability fixes, and long-term support

---

Why Upgrade?

1. Swift Concurrency Support (async/await)

Apollo iOS 2.0 was rebuilt from the ground up for Swift's modern concurrency model.

// Before (0.50.0) - Nested callbacks
client.fetch(query: MyQuery()) { result in
    switch result {
    case .success(let graphQLResult):
        guard let data = graphQLResult.data else { return }
        // handle data
    case .failure(let error):
        // handle error
    }
}

// After (2.0) - Clean async/await
do {
    let response = try await client.fetch(query: MyQuery())
    // use response.data directly
} catch {
    // handle error
}

2. Thread Safety & Data Race Prevention

• All core types (ApolloClient, ApolloStore, interceptors) conform to Sendable
• Compiler catches data races at build time instead of runtime crashes
• Full Swift 6 strict concurrency compatibility

3. Critical Bug Fixes

Issue	Fixed In
Data races in AsyncReadWriteLock	2.0.5
Deadlocks under heavy cache loads	2.0.4
Infinite loop in test mocks	2.0.4
Multipart parsing errors	2.0.3
Selection set equality issues	1.25.0

4. Platform Support

Platform	0.50.0	2.0
iOS	12.0+	15.0+
macOS	10.14+	12.0+
visionOS	❌	✅ 1.0+
Swift 6	❌	✅

---

Breaking Changes

Must Address

Change	Migration Effort
Minimum iOS 15	Audit user base; drop iOS 12-14
Async/await APIs	Update all fetch/mutate call sites
Interceptor framework	Rewrite custom interceptors
Cache policies	Update from unified enum to discrete types

Already Compatible

• ✅ Using Swift Package Manager (CocoaPods dropped in 2.0)
• ✅ Codegen infrastructure exists

Deferred (if applicable)

• WebSocket subscriptions: HTTP subscriptions work in 2.0; WebSocket support coming in 2.0.x

---

Migration Strategy

Option A: Direct to 2.0 (Recommended for new Swift concurrency adoption)

1. Update minimum deployment target to iOS 15
2. Update SPM dependency to 2.0.6
3. Run codegen to regenerate models
4. Migrate interceptors to new protocol-based architecture
5. Convert callback-based calls to async/await
6. Update cache policy usage

Option B: Incremental (1.x first, then 2.0)

1. Upgrade to latest 1.x for stability improvements
2. Plan separate 2.0 migration for async/await adoption

---

Risk Assessment

Risk	Mitigation
iOS 15 minimum	Check analytics - iOS 14 and below likely <5% of users
Migration time	Can be done incrementally; deprecated APIs still work initially
Testing	Existing unit tests + manual QA for network flows

---

Business Case

1. Security — 0.50.0 is 3+ years old with no security patches
2. Stability — Critical crash fixes only available in newer versions
3. Developer Velocity — async/await reduces networking code complexity by ~40%
4. Future-proofing — Swift 6 readiness, visionOS support
5. Community — 0.x branch is unmaintained; issues won't be addressed

---

Resources

• Apollo iOS Releases
• Apollo iOS 2.0 Announcement
• Migration Guide
• CHANGELOG

---

Prepared: February 2025