iOS 7: Using NSURLSession for Asynchronous Networking

In iOS 7, Apple introduced NSURLSession, which is a suite of classes that replaces NSURLConnection as the preferred method of networking. In this article, we cover the benefits of using NSURLSession, and when and how to use it.

What are the benefits of using NSURLSession?

There are a number of new advantages and benefits of using NSURLSession:

• Uploads and Downloads can be done in the Background
• When the NSURLSession is created, a configuration option can be selected to allow background networking. This helps to save battery life, supports multitasking and allows developers to use the same delegate model as in-process transfers.
• Allows the pause and resume for network operations
• When the NSURLSession API is utilized, any networking task can be paused, stopped and restarted. There is no NSOperation subclassing required.
• Configurable container for storing network request configuration
• Each NSURLSession provides a configurable container for storing network requests. For instance, for setting an HTTP header option, we will need to only do this once and each subsequent request will utilize the same configuration
• Allows a private storage which is subclassable. 
• Each NSURLSession is subclassable and one can configure a session to use private storage on a per session basis. This allows one to have private storage objects outside of the global state.
• Improved authentication handling
• When using NSURLConnection, if an authentication challenge was issued, the challenge would come back for an arbitrary request, so one would not know exactly what request was getting the challenge. However, with NSURLSession, the delegate handles the authentication.
• Rich delegate model
• NSURLConnection does have some asynchronous block based methods. However, a delegate cannot be used with them. 
• Uploads and downloads allowed through the file system. 
• This encourages a separation of the data (i.e. file contents) from the metadata (i.e. URL and settings)

NSURLSession

NSURLSession is designed as a replacement API for NSURLConnection. An NSURLSession is made using an NSURLSessionConfiguration with an optional delegate. After the session is established, the network requirements are satisfied by creating NSURLSessionTask.

According to Apple's URL Loading Programming Guide, you can use the NSURLSession API in two ways: with a system-provided delegate or with your own delegate. In general, you must use your own delegate if your app does any of the following:

• Uses background sessions to download or upload content while your app is not running.
• Performs custom authentication.
• Performs custom SSL certificate verification.
• Decides whether a transfer should be downloaded to disk or displayed based on the MIME type returned by the server or other similar criteria.
• Uploads data from a body stream (as opposed to an NSData object).
• Limits caching programmatically.
• Limits HTTP redirects programmatically.

If your app does not need to do any of these things, your app can use the system-provided delegates.

Basic sequence of method calls that your app needs to make and completion handler calls that your app receives when using NSURLSession with the system-provided delegate :

1. Create the NSURLSessionConfiguration
2. Create a session specifying a configuration object and a nil delegate.
3. Create task objects within a session that each represent a resource request. The task objects are subclasses of NSURLSessionTask—NSURLSessionDataTask, NSURLSessionUploadTask, or NSURLSessionDownloadTask, depending on the behavior you are trying to achieve.  These objects are analogous to NSURLConnection objects, but give you more control and a unified delegate model.
4. We need to have our delegate implement the required methods from the NSURLSessionDownloadDelegate protocol.
5. When a task completes, the NSURLSession object calls the task's completion handler.
6. When your app no longer needs a session, invalidate it by calling either either invalidateAndCancel (to cancel outstanding tasks) or finishTasksAndInvalidate (to allow outstanding tasks to finish before invalidating the object).

Important: If you are using the NSURLSession class without providing delegates, your app must create tasks using a call that takes a completionHandler parameter, because otherwise it cannot obtain data from the class.

Note: NSURLSession does not report server errors through the error parameter. The only errors your app receives through the error parameter are client-side errors, such as being unable to resolve the hostname or connect to the host. The error codes are described in URL Loading System Error Codes. Server-side errors are reported through the HTTP status code in the NSHTTPURLResponse object. For more information, read the documentation for the NSHTTPURLResponse and NSURLResponse classes.

Step #1: Creating the NSURLSessionConfiguration

There are three ways to create an NSURLSessionConfiguration:

• defaultSessionConfiguration 
• creates a configuration object that uses the global cache, cookie and credential storage objects. This configuration provides a session to look very much like the NSURLConnection.
• ephemeralSessionConfiguration
• This configuration is for "private" sessions and has no persistent storage for cache, cookie or credential storage objects
• backgroundSessionConfiguration
• This configuration is used for making networking calls from remote push notifications or while the app is suspended.

Once the NSURLSessionConfiguration is created, then the setting of various properties on it can be done as follows:

NSURLSessionConfiguration *sessionConfig = [NSURLSessionConfiguration defaultSessionConfiguration];   // restricts network operations to Wifi sessionConfig.allowsCellularAccess = NO;   // sets all requests to only accept JSON responses [sessionConfig setHTTPAdditionalHeaders: @{@"Accept": @"application/json"}];   // configures timeouts & restricts app to only have one network connection to a host sessionConfig.timeoutIntervalForRequest = 30.0; sessionConfig.timeoutIntervalForResource = 60.0; sessionConfig.HTTPMaximumConnectionsPerHost = 1;

Step #2: Creating the Session

With NSURLSession, you can create the tasks using the block based convenience methods, set up a delegate or both. For instance, if you want to download an image, then you will need to create an NSURLSessionDownloadTask.

// set the image URL NSString *imageUrl = @"http://someImage.png";   // create the default session configuration NSURLSessionConfiguration *sessionConfig = [NSURLSessionConfiguration defaultSessionConfiguration];   // create a session using the current class as a delegate NSURLSession *session = [NSURLSession sessionWithConfiguration:sessionConfig delegate:self delegateQueue:nil]; Step #3: Download the image by creating a task with a completion handler // the task is created from a session NSURLSessionDownloadTask *getImageTask = [session downloadTaskWithURL:[NSURL URLWithString:imageUrl]   completionHandler:^(NSURL *location, NSURLResponse *response, NSError *error) { // the image is uploaded as NSData UIImage *downloadedImage = [UIImage imageWithData: [NSData dataWithContentsOfURL:location]]; // update UIImageView image to show the new file dispatch_async(dispatch_get_main_queue(), ^{ // do stuff with image _imageWithBlock.image = downloadedImage; }); }];   // start up the task [getImageTask resume]; Step #4 Implementing the delegate methods We need to have our delegate implement some methods from the NSURLSessionDownloadDelegate protocol. For instance,  we need to get notified when the download is complete: -(void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didFinishDownloadingToURL:(NSURL *)location { // see code above from completion handler } Here we are provided with the location that the file is downloaded to so you can use it to work with the image. Tracking Download Progress. To track the download progress for either task creation method, do the following: -(void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didWriteData:(int64_t)bytesWritten totalBytesWritten:(int64_t)totalBytesWritten totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite { NSLog(@"%f / %f", (double)totalBytesWritten, (double)totalBytesExpectedToWrite); } Step #5: When the task is finished, URLSession:downloadTask:didFinishDownloadingToURL: is called.  In the case of a file download, this is when you can save the file from the temporary location to a permanent one. When the download fails or is cancelled, you can get the data to resume the download. NSURLSessionTask Both NSURLSessionDataTask and NSURLSessionDownloadTask are derived from NSURLSessionTask, which is the base class as illustrated below. Image: Courtesy of Ray Wenderlick's NSURLSession Tutorial NSURLSessionTask This is the base class for creating session tasks, which are generally one of the following subclasses. NSURLSessionDataTask This task is used for issuing HTTP GET requests to pull down data from servers. The data is returned in the form of NSData, which needs to be converted to the appropriate XML, JSON, etc. format. NSURLSessionDataTask *jsonData = [session dataTaskWithURL:yourNSURL completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) { // handle NSData }]; NSURLSessionUploadTask This class is used to upload something to a web service using HTTP POST or PUT commands. The delegate for the tasks also allows you to watch the network traffic while it is being transmitted. Upload an image: NSData *imageData = UIImageJPEGRepresentation(image, 0.6);   NSURLSessionUploadTask *uploadTask = [upLoadSession uploadTaskWithRequest:request fromData:imageData]; The task above is created from a session and the image is uploaded as NSData. Separate methods are available for uploading using files or a stream. NSURLSessionDownloadTask NSURLSessionDownloadTask makes it super-easy to download files from remote service and/or pause and resume the download at will. This subclass is a little different than the other two. This type of task writes directly to a temporary file. During the download the session will call NSURLSessionDownload URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite: to update status information When the task is finished, URLSession:downloadTask:didFinishDownloadingToURL: is called. This is when you can save the file from the temp location to a permanent one. When the download fails or is cancelled you can get the data to resume the download. This feature can be useful for downloading photos to your device's camera roll. We have covered the essential sequence of method calls required for NSURLSession when using a system provided delegate.  For further thorough documentation and detailed information on the NSURLSession and associated APIs, please refer to the Apple's URL Loading System Programming Guide or Ray Wenderlick's NSURLSession Tutorial . If you find this post helpful or want to share your experiences, feel free to send me comments here or follow me on Twitter @tasneemsayeed.  Have fun with NSURLSession Coding!