Declaration

Overview

The NSURLSession 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.

Important

The NSURLSession API involves many different classes working together in a fairly complex way that may not be obvious if you read the reference documentation by itself. Before using the API, read the overview in the URL Loading System topic. The articles in the First Steps, Uploading, and Downloading sections offer examples of performing common tasks with NSURLSession.

Using the NSURLSession 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).

Types of URL Sessions

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.

NSURLSession has a singleton sharedSession 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 NSURLSession 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.

Types of URL Session Tasks

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 NSURLSession 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.

Using a Session Delegate

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.

Important

The session object keeps a strong reference to the delegate until your app exits or explicitly invalidates the session. If you don’t invalidate the session, your app leaks memory until it exits.

Asynchronicity and URL Sessions

Like most networking APIs, the NSURLSession 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.

Protocol Support

The NSURLSession 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.

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

App Transport Security (ATS)

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 NSURLSession. ATS requires that HTTP connections use HTTPS (RFC 2818).

NSCopying Behavior

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.

Thread Safety

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.

Relationships

Inherits From

See Also

First Steps

A task, like downloading a specific resource, performed in a URL session.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.