iOS Networking

Build and review Apple-platform networking using URLSession with native async/await, structured concurrency, and Network.framework. Targets Swift 6.3 / iOS 26+.

Contents

• Core Principles
• Status Code Validation and Error Contract
• Foreground vs Background Transfers
• Route by Task
• Common Mistakes
• Review Checklist
• References

Core Principles

1. Prefer native async/await: Use URLSession.shared.data(for:), download(for:), and bytes(for:) for all foreground network operations.
2. Never swallow HTTP errors: URLSession only throws for transport-level failures (offline, DNS, timeout). It does not throw on 4xx or 5xx responses. Always validate (200..<300).contains(httpResponse.statusCode).
3. Keep retry policies bounded: Limit retries with exponential backoff and jitter. Only retry idempotent operations (GET, PUT, DELETE); never loop token refresh indefinitely.
4. Isolate shared state: Isolate token storage, refresh locks, and cookie management inside actors or serial synchronization queues.

Status Code Validation and Error Contract

let (data, response) = try await session.data(for: request)

guard let httpResponse = response as? HTTPURLResponse else {
    throw NetworkError.invalidResponse
}

guard (200..<300).contains(httpResponse.statusCode) else {
    throw NetworkError.httpError(statusCode: httpResponse.statusCode, data: data)
}

Differentiate error categories: transport errors (URLError), decoding errors (DecodingError), client errors (4xx), server errors (5xx), and cancellation (CancellationError).

Foreground vs Background Transfers

Route by Task

• For building reusable API clients, request encoders, authentication headers, and actors, read API Client and Request Building and Lightweight Clients.
• For resilient retries, certificate pinning, TLS security, and byte streaming, read Resilience, Security, and Streaming.
• For large file uploads, resume data, and progress tracking, read Uploads and Downloads and File Storage Patterns.
• For background transfers and app relaunch handlers, read Background Transfers. For real-time WebSockets, read WebSocket Networking.
• For cursor/offset pagination, AsyncSequence streams, and URLProtocol unit testing, read Pagination and URLProtocol Testing.
• For low-level TCP/UDP sockets, path monitoring, and cellular constraints with NWPathMonitor, read Network Framework.

Common Mistakes

• Assuming URLSession.data(for:) throws on HTTP 404 or 500 responses instead of inspecting statusCode.
• Using async/await convenience overloads on background URLSessionConfiguration, which requires delegate callbacks.
• Retrying non-idempotent POST requests automatically after a network timeout.
• Leaking NWPathMonitor instances or starting monitoring without setting a dispatch queue.
• Moving downloaded files after returning from urlSession(_:downloadTask:didFinishDownloadingTo:) (file is deleted upon return).

Review Checklist

• HTTP status code explicitly validated before decoding payload
• Transport errors separated from server-returned error payloads
• Safe retry policy with jitter applied only to idempotent requests
• Auth token refresh uses actor isolation to avoid redundant refresh calls
• Background sessions configure delegate and move temporary files synchronously
• URLProtocol tests verify 2xx, 4xx, 5xx, timeout, and cancellation states
• App Transport Security (ATS) exceptions avoided unless strictly necessary

References

• API client and request building
• Lightweight clients
• Resilience, security, and streaming
• Uploads and downloads
• File storage patterns
• Background transfers
• WebSocket networking
• Pagination and URLProtocol testing
• Network.framework and NWPathMonitor
• URLSession documentation
• URLRequest documentation