URLSessionConfiguration: The Blueprint for Network Requests

Why it exists

URLSessionConfiguration exists to separate the behavior of a networking stack from the execution of individual requests. Instead of configuring every request with timeouts, cache policies, and headers, you create a reusable template that defines these policies for an entire group of related requests managed by a URLSession.

The mental model

Think of URLSessionConfiguration as a blueprint for a URLSession. It's a set of instructions you create once, defining rules like timeouts, caching strategies, and custom headers. The URLSession is then built from this blueprint, and all its subsequent network tasks will automatically follow those rules, just like a construction crew follows a building plan.

How it works

You create an instance of URLSessionConfiguration using one of its three types. The .default configuration is a standard setup that uses a disk-based cache. The .ephemeral configuration creates a private session that doesn't save any data like caches, cookies, or credentials to disk. The .background configuration is for handling uploads or downloads when the app is not in the foreground.

After choosing a type, you customize its properties. For example, you can set timeoutIntervalForRequest to control how long to wait for a response, or add custom headers for all requests using httpAdditionalHeaders.

Finally, you pass this configuration object into the URLSession initializer. It's crucial to know that the URLSession makes a deep copy of the configuration. Any changes you make to your original configuration object after the session has been created will have no effect on that session.

When to use it

Use .default for most standard networking tasks where you want sensible caching behavior. Use .ephemeral for features like a private browsing mode or for any requests where you want to ensure no trace of the session is left on disk. Use .background for large file transfers that need to continue reliably even if the user switches to another app.

When not to use it

Do not try to configure the URLSession.shared singleton. It has a fixed, basic configuration and is not customizable. It's fine for very simple, one-off requests, but for anything requiring custom behavior—like specific timeouts or cache policies—you must create your own URLSession with a custom URLSessionConfiguration.

One canonical example

To create a session that times out requests after 10 seconds and adds a custom authorization header to every request, you would write: let config = URLSessionConfiguration.default config.timeoutIntervalForRequest = 10

config.httpAdditionalHeaders = ["Authorization": "Bearer YOUR_TOKEN"]
let session = URLSession(configuration: config)

Now, any data task created with this session will inherit these settings.