Inherits from NSObject
Declared in SPTRequest.h


This class provides convenience methods for talking to the Spotify Web API and wraps a customizable handler for requests which are used by those convenience methods.

All the functions for direct access to the api inside this class has been deprecated and moved out to their respective classes, for getting track metadata, look at SPTTrack, for getting featured playlists in browse, look at SPTBrowse and so on.

All model classes provide both convenience methods for getting content in the callback fashion, but also provides methods named createRequestFor... for creating NSURLRequests for calling the api directly with the request handler of choice, this allows you to do caching, cancellation and scheduling of calls in your own way. The model classes also provides methods for parsing a API Response back into a usable object, those are called ...fromData:withResponse:error, pluralized methods for getting multiple entities at once are also available when appropriate.

Example of using the API request creation / API response parser paradigm:

// Getting the first two pages of a playlists for a user
NSURLRequest *playlistrequest = [SPTPlaylistList createRequestForGettingPlaylistsForUser:@"possan" withAccessToken:accessToken error:nil];
[[SPTRequest sharedHandler] performRequest:playlistrequest callback:^(NSError *error, NSURLResponse *response, NSData *data) {
    if (error != nil) { Handle error }
    SPTPlaylistList *playlists = [SPTPlaylistList playlistListFromData:data withResponse:response error:nil];
    NSLog(@"Got possan's playlists, first page: %@", playlists);
    NSURLRequest *playlistrequest2 = [playlists createRequestForNextPageWithAccessToken:accessToken error:nil];
    [[SPTRequest sharedHandler] performRequest:playlistrequest2 callback:^(NSError *error2, NSURLResponse *response2, NSData *data2) {
        if (error2 != nil) { Handle error }
        SPTPlaylistList *playlists2 = [SPTPlaylistList playlistListFromData:data2 withResponse:response2 error:nil];
        NSLog(@"Got possan's playlists, second page: %@", playlists2);

Example without response body:

// Following a user
NSURLRequest *req = [SPTFollow createRequestForFollowingUsers:@[@"possan"]] withAccessToken:accessToken error:nil];
[[SPTRequest sharedHandler] performRequest:req callback:^(NSError *error, NSURLResponse *response, NSData *data) {
    long statusCode = ((NSHTTPURLResponse*)response).statusCode;
    switch (statusCode) {
        case 204:
            NSLog(@"Successfully followed user.");
        case 401:
        case 403:
            NSLog(@"Failed to follow user, are you sure your token is valid and have the correct scopes?");
            NSLog(@"Bork bork!");

Example of using convenience methods:

// Getting multiple artists
[SPTArtist artistsWithURIs:@[
        [NSURL URLWithString:@"spotify:artist:30Y7JOpiNgAGEhnkYPdI1P"],
        [NSURL URLWithString:@"spotify:artist:0jO0TlgxW9Il5JphAWzhR4"],
        [NSURL URLWithString:@"spotify:artist:0AKlaf8M1k8NjJp1uCOlTA"]
    accessToken:accessToken callback:^(NSError *error, id object) {
        NSLog(@"Got artists: %@", object);

API Console:

Class Methods


Helper function for creates an authenticated NSURLRequest for a Spotify API resource.

+ (NSURLRequest *)createRequestForURL:(NSURL *)url withAccessToken:(NSString *)accessToken httpMethod:(NSString *)httpMethod values:(id)values valueBodyIsJSON:(BOOL)encodeAsJSON sendDataAsQueryString:(BOOL)dataAsQueryString error:(NSError **)error



The HTTPS URL to request, this is a Spotify API URL, not a spotify URI.


A valid access token.


The HTTP method to use eg. GET POST etc.


The arguments to send to the URL


Encode arguments as an JSON object in the body of the request instead of QueryString encoding them.


Send arguments as a part of the query string instead of in the body of the request.


An optional NSError that will receive an error if request creation failed.

Return Value

A NSURLRequest

Declared In



Override the default request handler, this is where you’d implement your own if you want to, or use AFNetworking or similar

+ (void)setSharedHandler:(id<SPTRequestHandlerProtocol>)handler



New handler for requests

Declared In



Get a request handler

+ (id<SPTRequestHandlerProtocol>)sharedHandler

Declared In