THIS PROJECT IS DEPRECATED

🚨🚨🚨 Please, read the Deprecation Notice 🚨🚨🚨

Authentication and back-off logic is a pain, let's do it once and forget about it! This is a library that allows you to centralise this logic and forget about the ugly parts of making HTTP requests.

[x] 📱 iOS 10.0+
[x] 💻 OS X 10.12+
[x] ⌚️ watchOS 3.0+
[x] 📺 tvOS 10.0+

Yet another networking library? Well apart from some unique benefits such as built-in rate limiting and powerful request authentication, a significant benefit for you is that any tagged version has been tested in production. We only tag a new release once it’s been used for two weeks by the Spotify app (which has millions of active users a day). As such you can be sure tagged versions are as stable as possible.

As for Spotify, we wanted a light networking library that we had full control over in order to act fast in squashing bugs, and carefully select the feature we needed and were capable of supporting. The architecture also plays very nicely into our MVVM and view aggregation service architectures at Spotify by tying the lifetime of a request to the view.

Architecture :triangular_ruler:

SPTDataLoader is designed as an HTTP stack with 3 additional layers on top of NSURLSession.

The Application level, which controls the rate limiting and back-off policies per service, respecting the “Retry-After” header and knowing when or not it should retry the request.
The User level, which controls the authentication of the HTTP requests.
The View level, which allows automatic cancellation of requests the view has made upon deallocation.

Authentication

The authentication in this case is abstract, allowing the creator of the SPTDataLoaderFactory to define their own semantics for token acquisition and injection. It allows for asynchronous token acquisition if the token is invalid that seamlessly integrates with the HTTP request-response pattern.

Back-off policy

The data loader service allows rate limiting of URLs to be set explicitly or to be determined by the server using the “Retry-After” semantic. It allows back-off retrying by using a jittered exponential backoff to prevent the thundering hordes creating a request storm after a predictable exponential period has expired.

Installation :building_construction:

SPTDataLoader can be installed in a variety of ways, either as a dynamic framework, a static library, or through a dependency manager such as CocoaPods or Carthage.

Manually

Dynamic Framework

Drag the framework into the “Frameworks, Libraries, and Embedded Content” area in the “General” section of the target.

Static Library

Drag SPTDataLoader.xcodeproj into your App’s Xcode project and link your app with the library in the “Build Phases” section of the target.

CocoaPods

To integrate SPTDataLoader into your project using CocoaPods, add it to your Podfile:

pod 'SPTDataLoader', '~> 2.2'

Carthage

To integrate SPTDataLoader into your project using Carthage, add it to your Cartfile:

github "spotify/SPTDataLoader" ~> 2.2

Usage example :eyes:

For an example of this framework's usage, see the demo application SPTDataLoaderDemo in SPTDataLoader.xcodeproj. Just follow the instructions in ClientKeys.h.

Creating the SPTDataLoaderService

In your app you should only have 1 instance of SPTDataLoaderService, ideally you would construct this in something similar to an AppDelegate. It takes in a rate limiter, resolver, user agent and an array of NSURLProtocols. The rate limiter allows objects outside the service to change the rate limiting for different endpoints, the resolver allows overriding of host names, and the array of NSURLProtocols allows support for protocols other than http/s.

SPTDataLoaderRateLimiter *rateLimiter = [SPTDataLoaderRateLimiter rateLimiterWithDefaultRequestsPerSecond:10.0];
SPTDataLoaderResolver *resolver = [SPTDataLoaderResolver new];
self.service = [SPTDataLoaderService dataLoaderServiceWithUserAgent:@"Spotify-Demo"
                                                        rateLimiter:rateLimiter
                                                           resolver:resolver
                                           customURLProtocolClasses:nil];

Note that you can provide all these as nils if you are so inclined, it may be for the best to use nils until you identify a need for these different configuration options.

Defining your own SPTDataLoaderAuthoriser

If you don't need to authenticate your requests you can skip this. In order to authenticate your requests against a backend, you are required to create an implementation of the SPTDataLoaderAuthoriser, the demo project has an example in its SPTDataLoaderAuthoriserOAuth class. In this example we are checking if the request is for the domain which we are attempting to authenticate for, and then performing the authentication (in this case we are injecting an Auth Token into the HTTP header). This interface is asynchronous to allow you to perform token refreshes while a request is in flight in order to hold it until it is ready to be authenticated. Once you have a valid token you can call the delegate (which in this case will be the factory) in order to inform it that the request has been authenticated. Alternatively if you are unable to authenticate the request tell the delegate about the error.

Creating the SPTDataLoaderFactory

Your app should ideally only create an SPTDataLoaderFactory once your user has logged in or if you require no authentication for your calls. The factory controls the authorisation of the different requests against authoriser objects that you construct.

id<SPTDataLoaderAuthoriser> oauthAuthoriser = [[SPTDataLoaderAuthoriserOAuth alloc] initWithDictionary:oauthTokenDictionary];
self.oauthFactory = [self.service createDataLoaderFactoryWithAuthorisers:@[ oauthAuthoriser ]];

What we are doing here is using an implementation of an authoriser to funnel all the requests created by this factory into these authorisers.

Creating the SPTDataLoader

Your app should create an SPTDataLoader object per view that wants to make requests (e.g. it is best not too share these between classes). This is so when your view model is deallocated the requests made by your view model will also be cancelled.

SPTDataLoader *dataLoader = [self.oauthFactory createDataLoader];

Note that this data loader will only authorise requests that are made available by the authorisers supplied to its factory.

Creating the SPTDataLoaderRequest

In order to create a request the only information you will need is the URL and where the request came from. For more advanced requests see the properties on SPTDataLoaderRequest which let you change the method, timeouts, retries and whether to stream the results.

SPTDataLoaderRequest *request = [SPTDataLoaderRequest requestWithURL:meURL
                                                    sourceIdentifier:@"playlists"];
[self.dataLoader performRequest:request];

After you have made the request your data loader will call its delegate regarding results of the requests.

Handling Streamed Requests

Sometimes you will want to process HTTP requests as they come in packet by packet rather than receive a large callback at the end, this works better for memory and certain forms of media. For Spotify's purpose, it works for streaming MP3 previews of our songs. An example of using the streaming API:

void AudioSampleListener(void *, AudioFileStreamID, AudioFileStreamPropertyID, UInt32 *);
void AudioSampleProcessor(void *, UInt32, UInt32, const void *, AudioStreamPacketDescription *);

- (void)load
{
    NSURL *URL = [NSURL URLWithString:@"http://i.spotify.com/mp3_preview"];
    SPTDataLoaderRequest *request = [SPTDataLoaderRequest requestWithURL:URL sourceIdentifier:@"preview"];
    request.chunks = YES;
    [self.dataLoader performRequest:request];
}

- (void)dataLoader:(SPTDataLoader *)dataLoader
didReceiveDataChunk:(NSData *)data
       forResponse:(SPTDataLoaderResponse *)response
{
    [data enumerateByteRangesUsingBlock:^(const void *bytes, NSRange byteRange, BOOL *stop) {
        AudioFileStreamParseBytes(_audioFileStream, byteRange.length, bytes, 0);
    }];
}

- (void)dataLoader:(SPTDataLoader *)dataLoader didReceiveInitialResponse:(SPTDataLoaderResponse *)response
{
    AudioFileStreamOpen((__bridge void *)self,
                        AudioSampleListener,
                        AudioSampleProcessor,
                        kAudioFileMP3Type,
                        &_audioFileStream);
}

- (BOOL)dataLoaderShouldSupportChunks:(SPTDataLoader *)dataLoader
{
    return YES;
}

Be sure to render YES in your delegate to tell the data loader that you support chunks, and to set the requests chunks property to YES.

Rate limiting specific endpoints

If you specif

SPTDataLoader

Install / Use

README