URLSession

The URLSession class and related classes provide an API for downloading data from and uploading data to endpoints indicated by URLs. The API also enables your app to perform background downloads when your app isn’t running or, in iOS, while your app is suspended. A rich set of delegate methods support authentication and allow your app to be notified of events like redirection.

Using the URLSession API, your app creates one or more sessions, each of which coordinates a group of related data transfer tasks. For example, if you’re creating a web browser, your app might create one session per tab or window, or one session for interactive use and another for background downloads. Within each session, your app adds a series of tasks, each of which represents a request for a specific URL (following HTTP redirects, if necessary).

The tasks within a given URL session share a common session configuration object, which defines connection behavior, like the maximum number of simultaneous connections to make to a single host, whether to allow connections over a cellular network, and so on.

URLSession has a singleton shared session (which has no configuration object) for basic requests. It’s not as customizable as sessions you create, but it serves as a good starting point if you have very limited requirements. You access this session by calling the shared class method. For other kinds of sessions, you instantiate a URLSession with one of three kinds of configurations:

• A default session behaves much like the shared session, but allows more configuration, and allows you to obtain data incrementally with a delegate.

• Ephemeral sessions are similar to shared sessions, but don’t write caches, cookies, or credentials to disk.

• Background sessions let you perform uploads and downloads of content in the background while your app isn't running.

See Creating a Session Configuration Object in the URLSessionConfiguration class for details on creating each type of configuration.

Within a session, you create tasks that optionally upload data to a server and then retrieve data from the server either as a file on disk or as one or more NSData objects in memory. The URLSession API provides three types of tasks:

• Data tasks send and receive data using NSData objects. Data tasks are intended for short, often interactive requests to a server.

• Upload tasks are similar to data tasks, but they also send data (often in the form of a file), and support background uploads while the app isn’t running.

• Download tasks retrieve data in the form of a file, and support background downloads and uploads while the app isn’t running.

The tasks in a session also share a common delegate that lets you provide and obtain information when various events occur—when authentication fails, when data arrives from the server, when data is ready to be cached, and so on. If you don’t need any of the features provided by a delegate, you can use this API without providing one by passing nil when you create a session.

Like most networking APIs, the URLSession API is highly asynchronous. It returns data to your app in one of two ways, depending on the methods you call:

• By calling a completion handler block when a transfer finishes successfully or with an error.

• By calling methods on the session’s delegate as data is received and when the transfer is complete.

In addition to delivering this information to delegates, the URLSession API provides status and progress properties that you can query if you need to make programmatic decisions based on the current state of the task (with the caveat that its state can change at any time).

URL sessions also support canceling, restarting, resuming, and suspending tasks, and provide the ability to resume suspended, canceled, or failed downloads where they left off.

The URLSession class natively supports the data, file, ftp, http, and https URL schemes, with transparent support for proxy servers and SOCKS gateways, as configured in the user’s system preferences.

URLSession supports the HTTP/1.1 and HTTP/2 protocols. HTTP/2 support, as described by RFC 7540, requires a server supporting Application-Layer Protocol Negotiation (ALPN).

You can also add support for your own custom networking protocols and URL schemes (for your app’s private use) by subclassing URLProtocol.

Starting in iOS 9.0 and OS X 10.11, a new security feature called App Transport Security (ATS) is enabled by default for all HTTP connections made with URLSession. ATS requires that HTTP connections use HTTPS (RFC 2818).

For more information, see NSAppTransportSecurity in the Information Property List Key Reference.

Session and task objects conform to the NSCopying protocol as follows:

• When your app copies a session or task object, you get the same object back.

• When your app copies a configuration object, you get a new copy that you can independently modify.

The URL session API itself is fully thread-safe. You can freely create sessions and tasks in any thread context. When your delegate methods call the provided completion handlers, the work is automatically scheduled on the correct delegate queue.