Swift Networking

Lifecycle Position

Phase 3 (Implement). Load when building features that call external APIs or persist remote data.

Workflow Decision Tree

1. Build a REST API client

• Define a protocol-based API client (see references/networking-patterns.md )

• Use URLSession.shared.data(for:) for standard requests

• Decode responses with JSONDecoder configured for the API's conventions

• Handle errors at every layer: network → HTTP status → decode → domain

2. Download files

• Use URLSession.shared.download(from:) for large files

• Monitor progress with AsyncBytes or delegate

• Save to temporary directory, then move to final location

3. WebSocket communication

• Use URLSession.webSocketTask(with:) for real-time connections

• Handle .ping /.pong for keepalive

• Reconnect with exponential backoff on disconnect

4. Background transfers

• Create dedicated URLSessionConfiguration.background(withIdentifier:)

• Handle application(_:handleEventsForBackgroundURLSession:completionHandler:)

• Background transfers survive app termination

Core APIs

URLSession async/await

// GET request let (data, response) = try await URLSession.shared.data(from: url)

// POST with body var request = URLRequest(url: url) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try JSONEncoder().encode(payload) let (data, response) = try await URLSession.shared.data(for: request)

// Download let (localURL, response) = try await URLSession.shared.download(from: url)

// Stream bytes let (bytes, response) = try await URLSession.shared.bytes(from: url) for try await byte in bytes { /* process */ }

JSON Decoding

let decoder = JSONDecoder() decoder.keyDecodingStrategy = .convertFromSnakeCase decoder.dateDecodingStrategy = .iso8601

let result = try decoder.decode(MyModel.self, from: data)

Request Building

struct APIClient { let baseURL: URL let session: URLSession

func request<T: Decodable>(_ endpoint: String, method: String = "GET", body: (any Encodable)? = nil) async throws -> T {
    var request = URLRequest(url: baseURL.appendingPathComponent(endpoint))
    request.httpMethod = method
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    if let body { request.httpBody = try JSONEncoder().encode(body) }

    let (data, response) = try await session.data(for: request)
    guard let http = response as? HTTPURLResponse else {
        throw NetworkError.invalidResponse
    }
    guard (200...299).contains(http.statusCode) else {
        throw NetworkError.httpError(http.statusCode, data)
    }
    return try JSONDecoder().decode(T.self, from: data)
}

}

Error Handling Hierarchy

Handle errors from most specific to most general:

do { let user: User = try await api.request("/users/me") } catch let error as NetworkError { switch error { case .noConnection: // Show offline banner case .timeout: // Suggest retry case .httpError(401, _): // Redirect to login case .httpError(404, _): // Show not found case .httpError(429, _): // Rate limited — back off case .httpError(500..., _): // Server error — retry with backoff case .decodingFailed(let underlying): // Log, show generic error default: break } } catch is CancellationError { // Task was cancelled — do nothing } catch { // Unknown error — log and show generic message }

Retry with Exponential Backoff

func withRetry<T>(maxAttempts: Int = 3, operation: () async throws -> T) async throws -> T { for attempt in 0..<maxAttempts { do { return try await operation() } catch { if attempt == maxAttempts - 1 { throw error } let delay = UInt64(pow(2.0, Double(attempt))) * 1_000_000_000 try await Task.sleep(nanoseconds: delay) } } fatalError("Unreachable") }

URLSessionConfiguration

Configuration Use Case

.default

Standard requests with disk caching

.ephemeral

Sensitive data — no disk cache, no cookies persisted

.background(withIdentifier:)

Downloads/uploads that survive app termination

Key properties:

• timeoutIntervalForRequest — per-request timeout (default 60s, set to 30s for APIs)

• timeoutIntervalForResource — total transfer timeout (default 7 days)

• waitsForConnectivity — wait for network instead of failing immediately (set true for background)

• httpAdditionalHeaders — default headers for all requests (auth tokens, User-Agent)

Caching

// URL-level cache policy var request = URLRequest(url: url) request.cachePolicy = .returnCacheDataElseLoad // Offline-first

// Session-level cache let config = URLSessionConfiguration.default config.urlCache = URLCache(memoryCapacity: 10_000_000, diskCapacity: 50_000_000)

// ETag-based validation (automatic with .default configuration) // Server sends: ETag: "abc123" // Client sends: If-None-Match: "abc123" // Server returns 304 Not Modified if unchanged

Note: URLCache handles HTTP-level caching. For application-level persistence of fetched models (offline access, local repositories), use swift-actor-persistence .

Common Mistakes

• Force-unwrapping decoded data — always use try with proper error handling

• Missing timeout configuration — default 60s is too long for mobile APIs. Set 15-30s

• Not checking HTTP status code — data(for:) succeeds for 4xx/5xx responses. Always check HTTPURLResponse.statusCode

• Ignoring CancellationError — .task modifier cancels on disappear; don't show error UI for cancellation

• Building URLs with string concatenation — use URL(string:relativeTo:) or URLComponents to avoid encoding issues

Checklist

• Timeouts configured (15-30s for API calls)

• HTTP status codes checked (not just decode success)

• ATS exceptions documented in Info.plist if needed

• Errors surfaced to user with actionable messages

• Cancellation handled gracefully (no error UI for .task cancellation)

• No force-unwrap of decoded data

• Authentication tokens not hardcoded (use Keychain or environment)

• Retry logic for transient failures (429, 5xx)

Templates

Reusable Swift files in templates/ — copy and adapt for your project:

• APIClient.swift — Protocol-based API client with URLSession , typed endpoints, Sendable conformance

• APIEndpoint.swift — Protocol for typed API endpoints with path, method, body

• APIConfiguration.swift — Base URL and default headers configuration

• MockAPIClient.swift — Testing double implementing the APIClient protocol

• NetworkError.swift — Typed error enum for network failures

Cross-References

• swift-concurrency — async/await patterns, Task cancellation, actor isolation for network state

• swift-app-lifecycle — background transfer configuration

• ios-testing — mocking URLSession with protocol-based DI

• code-analyzer — network error handling review section

• swift-actor-persistence — actor-based local repositories for persisting fetched API data