Handling Redirects and Other Request Changes

A redirect occurs when a server responds to a request by indicating that the client should make a new request to a different URL. The NSURLSession class notify its delegate when this occurs.

To handle a redirect, your URL loading class delegate must implement the URLSession:task:willPerformHTTPRedirection:newRequest:completionHandler: delegate method

In this method, the delegate can examine the new request and the response that caused the redirect, and can return a new request object through the completion handler for NSURLSession.

The delegate can do any of the following:

In addition, the delegate can cancel both the redirect and the connection. With NSURLSession, the delegate does this by sending the cancel message to the task object.

The delegate also receives the URLSession:task:willPerformHTTPRedirection:newRequest:completionHandler: message if the NSURLProtocol subclass that handles the request has changed the NSURLRequest in order to standardize its format, for example, changing a request for http://www.apple.com to http://www.apple.com/. This occurs because the standardized, or canonical, version of the request is used for cache management. In this special case, the response passed to the delegate is nil and the delegate should simply return the provided request.

The example implementation in Listing 3-1 allows canonical changes and denies all server redirects.

Listing 3-1  Example of an implementation of URLSession:task:willPerformHTTPRedirection:newRequest:completionHandler

- (void)URLSession:(NSURLSession *)session
        task:(NSURLSessionTask *)task
        willPerformHTTPRedirection:(NSHTTPURLResponse *)redirectResponse
        newRequest:(NSURLRequest *)request
        completionHandler:(void (^)(NSURLRequest *))completionHandler
    NSURLRequest *newRequest = request;
    if (redirectResponse) {
        newRequest = nil;

If the delegate doesn’t provide an implementation for an appropriate redirect handling delegate method, all canonical changes and server redirects are allowed.