URLSession

What it is and why it exists

URLSession is the Foundation object that coordinates network transfers. One session creates tasks under shared rules for connections, cookies, credentials, caching, and protocol negotiation. Your application still defines each request, interprets each response, and decides what to do after failure.

The common data task collects a complete response body in memory, which suits short requests such as JSON API calls. Upload tasks explicitly provide data or a file, download tasks write response bodies to temporary files, and WebSocket tasks exchange messages. The task type changes how bytes are delivered, not the server’s HTTP contract.

URLSession.shared fits simple requests that need no special policy. When you need separate cookies, caches, timeouts, network-cost limits, or delegate callbacks, create a URLSessionConfiguration first and use it to make a reusable session. Background transfers also need a .background configuration with a stable identifier and a delegate.

URLSession solves transport on Apple platforms; it isn’t a complete API-client architecture. It won’t turn a 404 into a Swift error, validate business fields in JSON, refresh an access token, or decide whether a write can be retried. Those rules belong in visible, testable boundaries.

A typical repository or service receives a session and uses a small request builder to produce each URLRequest . Production code can then use a real session while tests use a controlled URLProtocol. Views and domain models don’t need to carry the networking details.

How it works

A regular asynchronous request follows this path:

URLComponents encodes path and query items into a URL. URLRequest adds the method, headers, body, cache policy, and per-request timeout. String concatenation can’t reliably handle reserved characters and makes it too easy to place tokens in a URL, so it shouldn’t do this job.

A session configuration defines policies shared by its tasks. .default uses persistent caching and shared cookie and credential stores; .ephemeral doesn’t persist those stores to disk; .background hands uploads or downloads to the system. Don’t move a short data request to a background session merely because the app may enter the background.

URLSession copies its configuration during initialization. Changing the original configuration later, or changing the copy returned by session.configuration, doesn’t affect that session. When policy must change, create another configuration and session, and define when the old session becomes invalid.

Calling data(for:) creates and starts a data task, then suspends the current Swift task until the full response arrives or transport fails. It returns (Data, URLResponse); a return value means URL loading completed, not that HTTP succeeded. Converting the response to HTTPURLResponse and checking its status is the client’s job.

Boundary code should distinguish at least three result layers:

This distinction tells callers where a request failed. Flattening everything into nil or one “request failed” string loses the facts needed to reauthenticate, retry, or locate a mismatched field. An application error needn’t expose every implementation detail, but it should retain the original cause for logs and tests.

Cancellation of a Swift concurrency task works with URLSession’s async methods. Yet cancellation is a request to stop waiting and working, not a server rollback protocol. If a request passed the remote commit point, a caller that observes cancellation or timeout may still have an unknown write outcome.

A session may use no delegate, a session delegate, or a per-task delegate. Delegates provide lifecycle hooks for authentication challenges, redirects, incremental data, progress, and background events. A session with a delegate retains it until the session is explicitly invalidated or the process exits, so ownership and invalidation must be designed together.

Caching first follows HTTP response headers and the request’s cache policy . URLCache can store cacheable responses by request. Saving an ETag manually without also managing the response body, Vary dimensions, and freshness rules usually creates a second, incomplete HTTP cache.

Examples

These four examples build a request, run a testable data task, configure a session, and isolate retry eligibility as a policy. They require Swift and Apple Foundation. This workspace has no Swift toolchain, so every code block is marked as unexecuted and no output block claims a run result.

Build a request without corrupting query values

The request builder expresses the path, query, and headers separately. URLComponents encodes the space in the search term, while the access token stays in the Authorization header.

The two force unwraps are provably safe for the fixed demonstration URL. Production code that reads user or configuration input should return a clear error instead. Keep path segments and query values separate: concatenating ?token=... risks broken encoding and puts a secret into histories and proxy logs.

Validate a response without using the real network

StubProtocol intercepts the request and returns a fixed HTTP response. The client still follows the real URLSession.data(for:) path, so the test covers request handling, status validation, and decoding without depending on an external service.

// # not executed here: Swift 6.3.3 toolchain is unavailable.
import Foundation

final class StubProtocol: URLProtocol {
    override class func canInit(with request: URLRequest) -> Bool { true }
    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }

    override func startLoading() {
        let response = HTTPURLResponse(
            url: request.url!, statusCode: 200,
            httpVersion: "HTTP/1.1", headerFields: ["Content-Type": "application/json"]
        )!
        let data = Data(#"{"id":7,"name":"Mina"}"#.utf8)
        client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
        client?.urlProtocol(self, didLoad: data)
        client?.urlProtocolDidFinishLoading(self)
    }

    override func stopLoading() {}
}

struct User: Decodable { let id: Int; let name: String }
enum ClientError: Error { case nonHTTP; case status(Int) }

let configuration = URLSessionConfiguration.ephemeral
configuration.protocolClasses = [StubProtocol.self]
let session = URLSession(configuration: configuration)
let request = URLRequest(url: URL(string: "https://api.example.test/users/7")!)
let (data, response) = try await session.data(for: request)

guard let http = response as? HTTPURLResponse else { throw ClientError.nonHTTP }
guard (200...299).contains(http.statusCode) else {
    throw ClientError.status(http.statusCode)
}

let user = try JSONDecoder().decode(User.self, from: data)
print("\(user.id): \(user.name)")

# not executed here: Swift 6.3.3 toolchain is unavailable.

The force unwraps here cover a fixed URL and an HTTP response constructor owned by the test. A production client should retain only a small, redacted portion of an error body; it mustn’t log returned HTML, tokens, or personal data wholesale. Decode after status validation so a 404 error object can’t masquerade as a model-format failure.

Freeze session policy

Finish the configuration before initializing a session. This example uses an ephemeral session to isolate persistent cookies, caches, and credentials, and it specifies separate timeouts for a request gap and the complete resource load.

// # not executed here: Swift 6.3.3 toolchain is unavailable.
import Foundation

let configuration = URLSessionConfiguration.ephemeral
configuration.timeoutIntervalForRequest = 12
configuration.timeoutIntervalForResource = 45
configuration.waitsForConnectivity = true
configuration.allowsExpensiveNetworkAccess = false
configuration.httpAdditionalHeaders = [
    "Accept": "application/json",
    "User-Agent": "CatalogApp/1.0",
]

let session = URLSession(configuration: configuration)
configuration.timeoutIntervalForRequest = 99

print(session.configuration.timeoutIntervalForRequest)
print(session.configuration.timeoutIntervalForResource)
print(session.configuration.allowsExpensiveNetworkAccess)
session.invalidateAndCancel()

# not executed here: Swift 6.3.3 toolchain is unavailable.

timeoutIntervalForRequest limits how long to wait for additional data, while timeoutIntervalForResource limits the total time available for a resource load. They aren’t the same deadline. waitsForConnectivity lets a task wait for a suitable network, but it doesn’t repair a connection that drops after establishment. Product requirements, not copied global defaults, should decide whether costly networks or Low Data Mode are allowed.

Retry only reads covered by policy

Retry eligibility belongs to the API contract, not to every error by default. This conservative policy considers only GET and HEAD, a small set of transient statuses, and a fixed attempt limit. Production timing should still honor Retry-After and add bounded jitter.

// # not executed here: Swift 6.3.3 toolchain is unavailable.
import Foundation

struct RetryPolicy {
    let maximumAttempts = 3
    let transientStatuses: Set<Int> = [408, 429, 500, 502, 503, 504]

    func permits(_ request: URLRequest, status: Int, attempt: Int) -> Bool {
        guard attempt < maximumAttempts else { return false }
        guard transientStatuses.contains(status) else { return false }
        return request.httpMethod == "GET" || request.httpMethod == "HEAD"
    }

    func fallbackDelay(after attempt: Int) -> TimeInterval {
        min(pow(2, Double(attempt - 1)), 8)
    }
}

let policy = RetryPolicy()
var get = URLRequest(url: URL(string: "https://api.example.com/items")!)
get.httpMethod = "GET"
var post = get
post.httpMethod = "POST"

print(policy.permits(get, status: 503, attempt: 1))
print(policy.permits(post, status: 503, attempt: 1))
print(policy.permits(get, status: 404, attempt: 1))
print(policy.fallbackDelay(after: 3))

# not executed here: Swift 6.3.3 toolchain is unavailable.

The policy deliberately doesn’t treat an idempotent method as sufficient by itself. Safe replay also requires a reproducible body, valid credentials, and enough deadline remaining. POST becomes safe to retry only when the server provides an application protocol such as a stable idempotency key backed by atomic deduplication.

Pitfalls

Treating transport completion as HTTP success

Fix: First require an HTTPURLResponse, then accept the endpoint’s specific success statuses, and only then decode the body. Preserve the status and a relevant request identifier for failures, while bounding and redacting any recorded body.

Building dynamic URLs with strings and force unwraps

Fix: Build layers with URL.appendingPathComponent and URLComponents.queryItems, and represent failure as an explicit error. Put credentials in the appropriate header and validate allowed schemes and hosts before sending.

Creating a session for every call

Fix: Reuse a session for each genuinely different policy, perhaps one each for interactive calls, ephemeral authentication, and background transfers. An owner with a custom delegate must choose finishTasksAndInvalidate() or invalidateAndCancel() and test the shutdown path.

Retrying writes unconditionally

Fix: Write a retry matrix by method, endpoint, and failure stage. Reads use bounded backoff and honor Retry-After; writes need an idempotency protocol, a stable key, and atomic server deduplication. Otherwise mark the result unknown and query operation status.

Hiding boundary failures with try? and raw bodies

Fix: Preserve the categories and causes of URLError, HTTP-status errors, and DecodingError. Log only a request ID, endpoint template, status, duration, and redacted error summary; tests should assert the precise failure layer.

Mistaking a foreground async call for background transfer

Fix: Use a background configuration with a fixed identifier, upload or download tasks, and persistent delegate state for long file transfers. Use default or ephemeral sessions for ordinary API calls, and make lifecycle interruption a recoverable product behavior.

Further reading

• Apple Developer Documentation: URLSession
• Apple Developer Documentation: URLSessionConfiguration
• WWDC21: Use async/await with URLSession
• Apple Developer Documentation: Accessing cached data
• Apple Developer Documentation: Downloading files in the background
• Swift.org: Installing Swift with Swiftly on macOS