api-integration

name	api-integration
description	Expert API integration decisions for iOS/tvOS: REST vs GraphQL trade-offs, API versioning strategies, caching layer design, and offline-first architecture choices. Use when designing network architecture, implementing offline support, or choosing between API patterns. Trigger keywords: REST, GraphQL, API versioning, caching, offline-first, URLSession, background fetch, ETag, pagination, rate limiting
version	3.0.0

API Integration — Expert Decisions

Expert decision frameworks for API integration choices. Claude knows URLSession and Codable — this skill provides judgment calls for architecture decisions and caching strategies.

---

Decision Trees

REST vs GraphQL

What's your data access pattern?
├─ Fixed, well-defined endpoints
│  └─ REST
│     Simpler caching, HTTP semantics
│
├─ Flexible queries, varying data needs per screen
│  └─ GraphQL
│     Single endpoint, client specifies shape
│
├─ Real-time subscriptions needed?
│  └─ GraphQL subscriptions or WebSocket + REST
│     GraphQL has built-in subscription support
│
└─ Offline-first with sync?
   └─ REST is simpler for conflict resolution
      GraphQL mutations harder to replay

The trap: Choosing GraphQL because it's trendy. If your API has stable endpoints and you control both client and server, REST is simpler.

API Versioning Strategy

How stable is your API?
├─ Stable, rarely changes
│  └─ No versioning needed initially
│     Add when first breaking change occurs
│
├─ Breaking changes expected
│  └─ URL path versioning (/v1/, /v2/)
│     Most explicit, easiest to manage
│
├─ Gradual migration needed
│  └─ Header versioning (Accept-Version: v2)
│     Same URL, version negotiated
│
└─ Multiple versions simultaneously
   └─ Consider if you really need this
      Maintenance burden is high

Caching Strategy Selection

What type of data?
├─ Static/rarely changes (images, config)
│  └─ Aggressive cache (URLCache + ETag)
│     Cache-Control: max-age=86400
│
├─ User-specific, changes occasionally
│  └─ Cache with validation (ETag/Last-Modified)
│     Always validate, but use cached if unchanged
│
├─ Frequently changing (feeds, notifications)
│  └─ No cache or short TTL
│     Cache-Control: no-cache or max-age=60
│
└─ Critical real-time data (payments, inventory)
   └─ No cache, always fetch
      Cache-Control: no-store

Offline-First Architecture

How important is offline?
├─ Nice to have (can show empty state)
│  └─ Simple memory cache
│     Clear on app restart
│
├─ Must show stale data when offline
│  └─ Persistent cache (Core Data, Realm, SQLite)
│     Fetch fresh when online, fallback to cache
│
├─ Must sync user changes when back online
│  └─ Full offline-first architecture
│     Local-first writes, sync queue, conflict resolution
│
└─ Real-time collaboration
   └─ Consider CRDTs or operational transforms
      Complex — usually overkill for mobile

---

NEVER Do

Service Layer Design

NEVER call NetworkManager directly from ViewModels:

// ❌ ViewModel knows about network layer
@MainActor
final class UserViewModel: ObservableObject {
    func loadUser() async {
        let response = try await NetworkManager.shared.request(APIRouter.getUser(id: "123"))
        // ViewModel parsing network response directly
    }
}

// ✅ Service layer abstracts network details
@MainActor
final class UserViewModel: ObservableObject {
    private let userService: UserServiceProtocol

    func loadUser() async {
        user = try await userService.getUser(id: "123")
        // ViewModel works with domain models
    }
}

NEVER expose DTOs beyond service layer:

// ❌ DTO leaks to ViewModel
func getUser() async throws -> UserDTO {
    try await networkManager.request(...)
}

// ✅ Service maps DTO to domain model
func getUser() async throws -> User {
    let dto: UserDTO = try await networkManager.request(...)
    return User(from: dto)  // Mapping happens here
}

NEVER hardcode base URLs:

// ❌ Can't change per environment
static let baseURL = "https://api.production.com"

// ✅ Environment-driven configuration
static var baseURL: String {
    #if DEBUG
    return "https://api.staging.com"
    #else
    return "https://api.production.com"
    #endif
}

// Better: Inject via configuration

Error Handling

NEVER show raw error messages to users:

// ❌ Exposes technical details
errorMessage = error.localizedDescription  // "JSON decoding error at keyPath..."

// ✅ Map to user-friendly messages
errorMessage = mapToUserMessage(error)

func mapToUserMessage(_ error: Error) -> String {
    switch error {
    case let networkError as NetworkError:
        return networkError.userMessage
    case is DecodingError:
        return "Unable to process response. Please try again."
    default:
        return "Something went wrong. Please try again."
    }
}

NEVER treat all errors the same:

// ❌ Same handling for all errors
catch {
    showErrorAlert(error.localizedDescription)
}

// ✅ Different handling per error type
catch is CancellationError {
    return  // User navigated away — not an error
}
catch NetworkError.unauthorized {
    await sessionManager.logout()  // Force re-auth
}
catch NetworkError.noConnection {
    showOfflineBanner()  // Different UI treatment
}
catch {
    showErrorAlert("Something went wrong")
}

Caching

NEVER cache sensitive data without encryption:

// ❌ Tokens cached in plain URLCache
URLCache.shared.storeCachedResponse(response, for: request)
// Login response with tokens now on disk!

// ✅ Exclude sensitive endpoints from cache
if endpoint.isSensitive {
    request.cachePolicy = .reloadIgnoringLocalCacheData
}

NEVER assume cached data is fresh:

// ❌ Trusts cache blindly
if let cached = cache.get(key) {
    return cached  // May be hours/days old
}

// ✅ Validate cache or show stale indicator
if let cached = cache.get(key) {
    if cached.isStale {
        Task { await refreshInBackground(key) }
    }
    return (data: cached.data, isStale: cached.isStale)
}

Pagination

NEVER load all pages at once:

// ❌ Memory explosion, slow initial load
func loadAllUsers() async throws -> [User] {
    var all: [User] = []
    var page = 1
    while true {
        let response = try await fetchPage(page)
        all.append(contentsOf: response.users)
        if response.users.isEmpty { break }
        page += 1
    }
    return all  // May be thousands of items!
}

// ✅ Paginate on demand
func loadNextPage() async throws {
    guard hasMorePages, !isLoading else { return }
    isLoading = true
    let response = try await fetchPage(currentPage + 1)
    users.append(contentsOf: response.users)
    currentPage += 1
    hasMorePages = !response.users.isEmpty
    isLoading = false
}

NEVER use offset pagination for mutable lists:

// ❌ Items shift during pagination
// User scrolls, new item added, page 2 now has duplicate
GET /users?offset=20&limit=20

// ✅ Cursor-based pagination
GET /users?after=abc123&limit=20
// Cursor is stable reference point

---

Essential Patterns

Service Layer with Caching

protocol UserServiceProtocol {
    func getUser(id: String, forceRefresh: Bool) async throws -> User
}

final class UserService: UserServiceProtocol {
    private let networkManager: NetworkManagerProtocol
    private let cache: CacheProtocol

    func getUser(id: String, forceRefresh: Bool = false) async throws -> User {
        let cacheKey = "user_\(id)"

        // Return cached if valid and not forcing refresh
        if !forceRefresh, let cached: User = cache.get(cacheKey), !cached.isExpired {
            return cached
        }

        // Fetch fresh
        let dto: UserDTO = try await networkManager.request(APIRouter.getUser(id: id))
        let user = User(from: dto)

        // Cache with TTL
        cache.set(cacheKey, value: user, ttl: .minutes(5))

        return user
    }
}

Stale-While-Revalidate Pattern

func getData() async -> (data: Data?, isStale: Bool) {
    // Immediately return cached (possibly stale)
    let cached = cache.get(key)

    // Refresh in background
    Task {
        do {
            let fresh = try await fetchFromNetwork()
            cache.set(key, value: fresh)
            // Notify UI of fresh data (publisher, callback, etc.)
            await MainActor.run { self.data = fresh }
        } catch {
            // Keep showing stale data
        }
    }

    return (data: cached?.data, isStale: cached?.isExpired ?? true)
}

Retry with Idempotency Key

struct CreateOrderRequest {
    let items: [OrderItem]
    let idempotencyKey: String  // Client-generated UUID
}

func createOrder(items: [OrderItem]) async throws -> Order {
    let idempotencyKey = UUID().uuidString

    return try await withRetry(maxAttempts: 3) {
        try await orderService.create(
            CreateOrderRequest(items: items, idempotencyKey: idempotencyKey)
        )
        // Server uses idempotencyKey to prevent duplicate orders
    }
}

Background Fetch Configuration

// In AppDelegate
func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    Task {
        do {
            let hasNewData = try await syncService.performBackgroundSync()
            completionHandler(hasNewData ? .newData : .noData)
        } catch {
            completionHandler(.failed)
        }
    }
}

// In Info.plist: UIBackgroundModes = ["fetch"]
// Call: UIApplication.shared.setMinimumBackgroundFetchInterval(...)

---

Quick Reference

API Architecture Decision Matrix

Factor	REST	GraphQL
Fixed endpoints	✅ Best	Overkill
Flexible queries	Verbose	✅ Best
Caching	✅ HTTP native	Complex
Real-time	WebSocket addition	✅ Subscriptions
Offline sync	✅ Easier	Harder
Learning curve	Lower	Higher

Caching Strategy by Data Type

Data Type	Strategy	TTL
App config	Aggressive	24h
User profile	Validate	5-15m
Feed/timeline	Short or none	1-5m
Payments	None	0
Images	Aggressive	7d

Red Flags

Smell	Problem	Fix
DTO in ViewModel	Coupling to API	Map to domain model
Hardcoded base URL	Can't switch env	Configuration
Showing DecodingError	Leaks internals	User-friendly messages
Loading all pages	Memory explosion	Paginate on demand
Offset pagination for mutable data	Duplicates/gaps	Cursor pagination
Caching auth responses	Security risk	Exclude sensitive