Networking with URLSession
URLSession is the foundation networking API used across all Apple platforms for making HTTP(S) requests, downloading and uploading files, and managing background transfers. Modern Swift code overwhelmingly uses URLSession's async/await interface, data(for:) and data(from:), which lets you await a network call directly inside an async function without callback nesting. Under the hood, URLSession still manages connection pooling, TLS, caching, and cookie handling the same way it always has; async/await is a thin, structured-concurrency-friendly wrapper around the same session machinery that previously used completion handlers.
Cricket analogy: Just as DRS review technology sits on top of the same umpiring rules that have always governed the game, URLSession's async/await data(for:) is a thin wrapper over the same connection pooling, TLS, and caching machinery that completion-handler networking always used.
Making a Basic Request
The simplest pattern is URLSession.shared.data(from: url), which returns a tuple of (Data, URLResponse) or throws. URLSession.shared is a singleton session appropriate for simple, ad-hoc requests; for finer control over caching policy, timeout intervals, or authentication, you create a custom URLSession with a URLSessionConfiguration. Always inspect the URLResponse — cast it to HTTPURLResponse to read the status code, since a non-2xx status does not throw an error by itself; URLSession only throws for transport-level failures like no connectivity or a cancelled request.
Cricket analogy: Just as a club match can use the ground's shared, basic scoreboard for casual games but a televised international needs a custom Hawk-Eye rig, a scorer must still check the actual result posted — a non-2xx status doesn't automatically raise an appeal, mirroring HTTPURLResponse checks.
struct APIClient {
func fetchUser(id: Int) async throws -> Data {
guard let url = URL(string: "https://api.example.com/users/\(id)") else {
throw URLError(.badURL)
}
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.setValue("application/json", forHTTPHeaderField: "Accept")
let (data, response) = try await URLSession.shared.data(for: request)
guard let httpResponse = response as? HTTPURLResponse,
(200...299).contains(httpResponse.statusCode) else {
throw URLError(.badServerResponse)
}
return data
}
}POST Requests and Uploading Data
For requests that send a body, such as POST or PUT, you set request.httpBody to encoded Data (commonly JSON from JSONEncoder) and set the Content-Type header accordingly. URLSession.upload(for:from:) is preferred over setting httpBody directly when uploading large payloads, because it can stream the body rather than holding it entirely in memory. For very large files or transfers that must survive app suspension, URLSessionConfiguration.background(withIdentifier:) creates a background session that the system continues even if your app is terminated, later relaunching it to deliver the result.
Cricket analogy: Just as sending a full match report by courier works for a club game but a broadcaster streams live footage continuously for a televised series, a Test match's data must keep recording even if the stadium's power briefly cuts, mirroring httpBody versus upload(for:from:) and background sessions.
func createUser(_ payload: NewUserRequest) async throws -> UserDTO {
var request = URLRequest(url: URL(string: "https://api.example.com/users")!)
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)
guard let http = response as? HTTPURLResponse, http.statusCode == 201 else {
throw URLError(.badServerResponse)
}
return try JSONDecoder().decode(UserDTO.self, from: data)
}Cancellation and Structured Concurrency
Because async/await URLSession calls run inside Tasks, they integrate naturally with Swift's cooperative cancellation. If the enclosing Task is cancelled — for example, a SwiftUI view using .task {} disappears — the in-flight request is cancelled automatically and data(for:) throws a CancellationError or URLError(.cancelled). This eliminates a whole category of bugs from the completion-handler era, where a callback could fire after a view controller had already been dismissed, requiring manual weak self bookkeeping and cancellation flags.
Cricket analogy: Just as a substitute fielder immediately stops chasing a ball the moment the umpire calls it dead, a SwiftUI view's .task {} request is automatically cancelled the instant the view disappears, throwing CancellationError instead of leaving a ghost callback like the old weak-self bookkeeping era.
URLSession's async APIs don't replace URLSessionDelegate; you can still supply a delegate to data(for:delegate:) for progress reporting, authentication challenges, or redirect handling, combining structured concurrency with fine-grained callbacks where needed.
A common mistake is treating any successful try await as a successful HTTP response. URLSession does not throw for 4xx/5xx status codes — you must check HTTPURLResponse.statusCode yourself, or errors from the server will silently be decoded as if they were valid data.
URLSession.shared.data(for:)/data(from:)provide async/await network calls that return(Data, URLResponse).- URLSession only throws for transport failures; HTTP status codes must be checked manually via
HTTPURLResponse. - Use
URLRequestto configure method, headers, and body for non-GET requests. URLSession.upload(for:from:)streams large request bodies instead of buffering them fully in memory.- Background sessions (
URLSessionConfiguration.background) let transfers continue after app suspension or termination. - Async requests are automatically cancelled when their enclosing
Taskis cancelled, simplifying lifecycle management.
Practice what you learned
1. What does `URLSession.shared.data(for:)` return when awaited successfully?
2. Does URLSession throw an error when the server responds with a 404 status code?
3. What happens to an async URLSession request if its enclosing Task is cancelled?
4. Why would you use `URLSession.upload(for:from:)` instead of setting `request.httpBody` directly?
5. What is the purpose of a background URLSessionConfiguration?
Was this page helpful?
You May Also Like
Codable and JSON Parsing
Learn how Swift's Codable protocol pair enables automatic, type-safe encoding and decoding between Swift types and formats like JSON.
async/await Basics in Swift
Learn how Swift's async/await syntax replaces completion-handler callbacks with linear, readable asynchronous code, and how to call async functions safely.
Task and Structured Concurrency
Explore how Swift's Task type creates units of asynchronous work, how structured concurrency establishes parent-child relationships, and how cancellation propagates.
Unit Testing ViewModels in Swift
Learn how to write focused, reliable unit tests for SwiftUI ViewModels using XCTest or Swift Testing, including async code and dependency injection.