Access Twitter's REST API

The REST API can be used to make authenticated Twitter API requests. Though it can be accessed manually, we recommend using the convenience methods whenever possible.

Use the Provided Convenience Methods

NOTE: You must have previously completed the login flow for the user in order for this method to work.

Construct a Twitter API Client

Version 1.10.0 of TwitterKit adopted a model for making API requests that requires developer to more explicitly express their intentions about who the request is being made on behalf of. This model was introduced because a single shared API client model is not safe to use when making network requests around the time of logging in or out or when working with multiple users. The asynchronous nature of networking can introduce subtle bugs when using a single, mutable client unless great care is taken. TwitterKit attempts to solve this problem by requiring that an API client be created with an explicit user or guest context specified and not allowing it to be changed for the lifetime of the object. TWTRAPIClient's are very lightweight objects so it is safe to make a new client for each request or to hold on to one client for the lifetime of your application.

Creating an API client which uses guest context.

// Objective-C
TWTRAPIClient *client = [[TWTRAPIClient alloc] init];

// make requests with client

// Swift
let client = TWTRAPIClient()

// make requests with client

Creating an API client which uses a user context

// Objective-C

// Get the current userID. This value should be managed by the developer but can be retrieved from the TWTRSessionStore.
NSString *userID = [Twitter sharedInstance].sessionStore.session.userID;
TWTRAPIClient *client = [[TWTRAPIClient alloc] initWithUserID:userID];

// make requests with client

// Swift
// Get the current userID. This value should be managed by the developer but can be retrieved from the TWTRSessionStore.
if let userID = Twitter.sharedInstance().sessionStore.session()?.userID {
  let client = TWTRAPIClient(userID: userID)
  // make requests with client
}

NOTE: Prior to version 1.10.0 there was a single API client stored on the Twitter shared instance. It can be retrieved by calling [[Twitter sharedInstance] APIClient]

Load a Single Tweet

Load a single tweet to show in a Regular style tweet:

// Objective-C
// Fetches @jack's first Tweet
TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
[client loadTweetWithID:@"20" completion:^(TWTRTweet *tweet, NSError *error) {
  // handle the response or error
}];

// Swift
// Fetches @jack's first Tweet
let client = TWTRAPIClient()
client.loadTweetWithID("20") { (tweet, error) -> Void in
  // handle the response or error
}

Load Multiple Tweets

// Objective-C
TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
NSArray *tweetIDs = @[@"20", @"510908133917487104"];
[client loadTweetsWithIDs:tweetIDs completion:^(NSArray *tweets, NSError *error) {
  // handle the response or error
}];

// Swift
let client = TWTRAPIClient()
let tweetIDs = ["20", "510908133917487104"]
client.loadTweets(withIDs: tweetIDs) { (tweets, error) -> Void in
  // handle the response or error
}

Load a User

If you are looking to load a single user:

// Objective-C
TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
[client loadUserWithID:@"12" completion:^(TWTRUser *user, NSError *error) {
  // handle the response or error
}];

// Swift
let client = TWTRAPIClient()
client.loadUser(withID: "12") { (user, error) -> Void in
  // handle the response or error
}

Construct a Twitter Request Manually

If you want to to access other Twitter API endpoints, you may choose to construct a request manually. For example, you might do something like this:

// Objective-C
TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
NSString *statusesShowEndpoint = @"https://api.twitter.com/1.1/statuses/show.json";
NSDictionary *params = @{@"id" : @"20"};
NSError *clientError;

NSURLRequest *request = [client URLRequestWithMethod:@"GET" URL:statusesShowEndpoint parameters:params error:&clientError];

if (request) {
    [client sendTwitterRequest:request completion:^(NSURLResponse *response, NSData *data, NSError *connectionError) {
        if (data) {
            // handle the response data e.g.
            NSError *jsonError;
            NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:&jsonError];
        }
        else {
            NSLog(@"Error: %@", connectionError);
        }
    }];
}
else {
    NSLog(@"Error: %@", clientError);
}

// Swift
let client = TWTRAPIClient()
let statusesShowEndpoint = "https://api.twitter.com/1.1/statuses/show.json"
let params = ["id": "20"]
var clientError : NSError?

let request = client.urlRequest(withMethod: "GET", url: statusesShowEndpoint, parameters: params, error: &clientError)

client.sendTwitterRequest(request) { (response, data, connectionError) -> Void in
    if connectionError != nil {
        print("Error: \(connectionError)")
    }

    do {
        let json = try JSONSerialization.jsonObject(with: data!, options: [])
        print("json: \(json)")
    } catch let jsonError as NSError {
        print("json error: \(jsonError.localizedDescription)")
    }
}