FBRequest
This class is no longer available in the most recent version of the SDK.
A more recent version of this class is available. Check out the latest version.

The FBRequest object is used to setup and manage requests to Facebook Graph and REST APIs. This class provides helper methods that simplify the connection and response handling.

Discussion:

An FBSession object is required for all authenticated uses of FBRequest. Requests that do not require an unauthenticated user are also supported and do not require an FBSession object to be passed in.

An instance of FBRequest represents the arguments and setup for a connection to Facebook. After creating an FBRequest object it can be used to setup a connection to Facebook through the FBRequestConnection object. The FBRequestConnection object is created to manage a single connection. To cancel a connection use the instance method in the FBRequestConnection class.

An FBRequest object may be reused to issue multiple connections to Facebook. However each FBRequestConnection instance will manage one connection.

Class and instance methods prefixed with **start* ** can be used to perform the request setup and initiate the connection in a single call.

Inherits from:NSObject
Declared in:FBRequest.h
Properties
graphObject

The graph object to post with the request.

@property (nonatomic, retain) id<FBGraphObject> graphObject;
Discussion:

May be used to read the graph object that was automatically set during the object initiliazation. Make any required modifications prior to sending the request.

Declared In: FBRequest.h
graphPath

The Graph API endpoint to use for the request, for example "me".

@property (nonatomic, copy) NSString *graphPath;
Discussion:

May be used to read the Graph API endpoint that was automatically set during the object initiliazation. Make any required modifications prior to sending the request.

Declared In: FBRequest.h
HTTPMethod

The HTTPMethod to use for the request, for example "GET" or "POST".

@property (nonatomic, copy) NSString *HTTPMethod;
Discussion:

May be used to read the HTTP method that was automatically set during the object initiliazation. Make any required modifications prior to sending the request.

Declared In: FBRequest.h
parameters

The parameters for the request.

@property (nonatomic, retain, readonly) NSMutableDictionary *parameters;
Discussion:

May be used to read the parameters that were automatically set during the object initiliazation. Make any required modifications prior to sending the request.

NSString parameters are used to generate URL parameter values or JSON parameters. NSData and UIImage parameters are added as attachments to the HTTP body and referenced by name in the URL and/or JSON.

Declared In: FBRequest.h
restMethod

A valid REST API method.

@property (nonatomic, copy) NSString *restMethod;
Discussion:

May be used to read the REST method that was automatically set during the object initiliazation. Make any required modifications prior to sending the request.

Use the Graph API equivalent of the API if it exists as the REST API method is deprecated if there is a Graph API equivalent.

Declared In: FBRequest.h
session

The FBSession session object to use for the request.

@property (nonatomic, retain) FBSession *session;
Discussion:

May be used to read the session that was automatically set during the object initiliazation. Make any required modifications prior to sending the request.

Declared In: FBRequest.h
Class Methods
requestForCustomAudienceThirdPartyID:

Creates a request representing the Graph API call to retrieve a Custom Audience "thirdy party ID" for the app's Facebook user. Callers will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with, and then use the resultant Custom Audience to target ads.

ParameterDescription
session

The FBSession to use to establish the user's identity for users logged into Facebook through this app. If nil, then the activeSession is used.

+ (FBRequest *) requestForCustomAudienceThirdPartyID:(FBSession *)session;
Discussion:

This method will throw an exception if [FBSettings defaultAppID] is nil. The appID won't be nil when the pList includes the appID, or if it's explicitly set.

The JSON in the request's response will include an "custom_audience_third_party_id" key/value pair, with the value being the ID retrieved. This ID is an encrypted encoding of the Facebook user's ID and the invoking Facebook app ID. Multiple calls with the same user will return different IDs, thus these IDs cannot be used to correlate behavior across devices or applications, and are only meaningful when sent back to Facebook for creating Custom Audiences.

The ID retrieved represents the Facebook user identified in the following way: if the specified session (or activeSession if the specified session is nil) is open, the ID will represent the user associated with the activeSession; otherwise the ID will represent the user logged into the native Facebook app on the device. If there is no native Facebook app, no one is logged into it, or the user has opted out at the iOS level from ad tracking, then a nil ID will be returned.

This method returns nil if either the user has opted-out (via iOS) from Ad Tracking, the app itself has limited event usage via the [FBAppEvents setLimitEventUsage] flag, or a specific Facebook user cannot be identified.

Declared In: FBRequest.h
requestForDeleteObject:

Creates request representing a DELETE to a object.

ParameterDescription
object

This can be an NSString, NSNumber or NSDictionary representing an object to delete

+ (FBRequest *) requestForDeleteObject:(id)object;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForGraphPath:

Returns a newly initialized request object that can be used to make a Graph API call for the active session.

ParameterDescription
graphPath

The Graph API endpoint to use for the request, for example "me".

+ (FBRequest *) requestForGraphPath:(NSString *)graphPath;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForMe

Creates a request representing a Graph API call to the "me" endpoint, using the active session.

+ (FBRequest *) requestForMe;
Discussion:

Simplifies preparing a request to retrieve the user's identity.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

A successful Graph API call will return an FBGraphUser object representing the user's identity.

Note you may change the session property after construction if a session other than the active session is preferred.

Declared In: FBRequest.h
requestForMyFriends

Creates a request representing a Graph API call to the "me/friends" endpoint using the active session.

+ (FBRequest *) requestForMyFriends;
Discussion:

Simplifies preparing a request to retrieve the user's friends.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

A successful Graph API call will return an array of FBGraphUser objects representing the user's friends.

Declared In: FBRequest.h
requestForPlacesSearchAtCoordinate:radiusInMeters:resultsLimit:searchText:

Creates a request representing a Graph API call to the "search" endpoint for a given location using the active session.

ParameterDescription
coordinate

The search coordinates.

radius

The search radius in meters.

limit

The maxiumum number of results to return. It is possible to receive fewer than this because of the radius and because of server limits.

searchText

The text to use in the query to narrow the set of places returned.

+ (FBRequest *)
requestForPlacesSearchAtCoordinate
CLLocationCoordinate
D
coordinate
radiusInMeters: (NSInteger)radius
resultsLimit: (NSInteger)limit
searchText: (NSString *)searchText;
Discussion:

Simplifies preparing a request to search for places near a coordinate.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

A successful Graph API call will return an array of FBGraphPlace objects representing the nearby locations.

Declared In: FBRequest.h
requestForPostOpenGraphObject:

Returns a newly initialized request object that can be used to create a user owned Open Graph object for the active session.

ParameterDescription
object

The Open Graph object to create. Some common expected fields include "title", "image", "url", etc.

+ (FBRequest *) requestForPostOpenGraphObject:(id<FBOpenGraphObject>)object;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForPostOpenGraphObjectWithType:title:image:url:description:objectProperties:

Returns a newly initialized request object that can be used to create a user owned Open Graph object for the active session.

ParameterDescription
type

The fully-specified Open Graph object type (e.g., my_app_namespace:my_object_name)

title

The title of the Open Graph object.

image

The link to an image to be associated with the Open Graph object.

url

The url to be associated with the Open Graph object.

description

The description to be associated with the object.

objectProperties

Any additional properties for the Open Graph object.

+ (FBRequest *)
requestForPostOpenGraphObjectWithType: (NSString *)type
title: (NSString *)title
image: (id)image
url: (id)url
description: (NSString *)description
objectProperties: (NSDictionary *)objectProperties;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForPostStatusUpdate:

Creates a request representing a status update.

ParameterDescription
message

The message to post.

+ (FBRequest *) requestForPostStatusUpdate:(NSString *)message;
Discussion:

Simplifies preparing a request to post a status update.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForPostStatusUpdate:place:tags:

Creates a request representing a status update.

ParameterDescription
message

The message to post.

place

The place to checkin with, or nil. Place may be an fbid or a graph object representing a place.

tags

Array of friends to tag in the status update, each element may be an fbid or a graph object representing a user.

+ (FBRequest *)
requestForPostStatusUpdate: (NSString *)message
place: (id)place
tags: (id<NSFastEnumeration>)tags;
Discussion:

Simplifies preparing a request to post a status update.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForPostWithGraphPath:graphObject:

Creates a request representing a POST for a graph object.

ParameterDescription
graphPath

The Graph API endpoint to use for the request, for example "me".

graphObject

An object or open graph action to post.

+ (FBRequest *)
requestForPostWithGraphPath: (NSString *)graphPath
graphObject: (id<FBGraphObject>)graphObject;
Discussion:

This method is typically used for posting an open graph action. If you are only posting an open graph object (without an action), consider using requestForPostOpenGraphObject:

Declared In: FBRequest.h
requestForUpdateOpenGraphObject:

Returns a newly initialized request object that can be used to update a user owned Open Graph object for the active session.

ParameterDescription
object

The Open Graph object to update the existing object with.

+ (FBRequest *) requestForUpdateOpenGraphObject:(id<FBOpenGraphObject>)object;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForUpdateOpenGraphObjectWithId:title:image:url:description:objectProperties:

Returns a newly initialized request object that can be used to update a user owned Open Graph object for the active session.

ParameterDescription
objectId

The id of the Open Graph object to update.

title

The updated title of the Open Graph object.

image

The updated link to an image to be associated with the Open Graph object.

url

The updated url to be associated with the Open Graph object.

description

The updated description of the Open Graph object.

objectProperties

Any additional properties to update for the Open Graph object.

+ (FBRequest *)
requestForUpdateOpenGraphObjectWithId: (id)objectId
title: (NSString *)title
image: (id)image
url: (id)url
description: (NSString *)description
objectProperties: (NSDictionary *)objectProperties;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForUploadPhoto:

Creates a request representing a Graph API call to upload a photo to the app's album using the active session.

ParameterDescription
photo

A UIImage for the photo to upload.

+ (FBRequest *) requestForUploadPhoto:(UIImage *)photo;
Discussion:

Simplifies preparing a request to post a photo.

To post a photo to a specific album, get the FBRequest returned from this method call, then modify the request parameters by adding the album ID to an "album" key.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestForUploadStagingResourceWithImage:

Returns a newly initialized request object that can be used to upload an image to create a staging resource. Staging resources allow you to post binary data such as images, in preparation for a post of an open graph object or action which references the image. The URI returned when uploading a staging resource may be passed as the image property for an open graph object or action.

ParameterDescription
image

A UIImage for the image to upload.

+ (FBRequest *) requestForUploadStagingResourceWithImage:(UIImage *)image;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
requestWithGraphPath:parameters:HTTPMethod:

Returns a newly initialized request object that can be used to make a Graph API call for the active session.

ParameterDescription
graphPath

The Graph API endpoint to use for the request, for example "me".

parameters

The parameters for the request. A value of nil sends only the automatically handled parameters, for example, the access token. The default is nil.

HTTPMethod

The HTTP method to use for the request. A nil value implies a GET.

+ (FBRequest *)
requestWithGraphPath: (NSString *)graphPath
parameters: (NSDictionary *)parameters
HTTPMethod: (NSString *)HTTPMethod;
Discussion:

This method simplifies the preparation of a Graph API call.

This method does not initialize an FBRequestConnection object. To initiate the API call first instantiate an FBRequestConnection object, add the request to this object, then call the start method on the connection instance.

Declared In: FBRequest.h
Instance Methods
initForPostWithSession:graphPath:graphObject:

Initialize a FBRequest object that will do a graph request.

ParameterDescription
session

The session object representing the identity of the Facebook user making the request. A nil value indicates a request that requires no token; to use the active session pass [FBSession activeSession].

graphPath

The Graph API endpoint to use for the request, for example "me".

graphObject

An object or open graph action to post.

- (instancetype)
initForPostWithSession: (FBSession *)session
graphPath: (NSString *)graphPath
graphObject: (id<FBGraphObject>)graphObject;
Discussion:

Note that this only sets properties on the FBRequest.

To send the request, initialize a FBRequestConnection, add this request, and send [FBRequestConnection start]. See other methods on this class for shortcuts to simplify this process.

Declared In: FBRequest.h
initWithSession:graphPath:
ParameterDescription
session

The session object representing the identity of the Facebook user making the request. A nil value indicates a request that requires no token; to use the active session pass [FBSession activeSession].

graphPath

The Graph API endpoint to use for the request, for example "me".

- (instancetype)
initWithSession: (FBSession *)session
graphPath: (NSString *)graphPath;
Discussion:

Calls initWithSession:graphPath:parameters:HTTPMethod: with default parameters except for the ones provided to this method.

Declared In: FBRequest.h
initWithSession:graphPath:parameters:HTTPMethod:

Initializes an FBRequest object for a Graph API request call.

ParameterDescription
session

The session object representing the identity of the Facebook user making the request. A nil value indicates a request that requires no token; to use the active session pass [FBSession activeSession].

graphPath

The Graph API endpoint to use for the request, for example "me".

parameters

The parameters for the request. A value of nil sends only the automatically handled parameters, for example, the access token. The default is nil.

HTTPMethod

The HTTP method to use for the request. The default is value of nil implies a GET.

- (instancetype)
initWithSession: (FBSession *)session
graphPath: (NSString *)graphPath
parameters: (NSDictionary *)parameters
HTTPMethod: (NSString *)HTTPMethod;
Discussion:

Note that this only sets properties on the FBRequest object.

To send the request, initialize an FBRequestConnection object, add this request, and send [FBRequestConnection start]. See other methods on this class for shortcuts to simplify this process.

Declared In: FBRequest.h
initWithSession:restMethod:parameters:HTTPMethod:

Initialize a FBRequest object that will do a rest API request.

ParameterDescription
session

The session object representing the identity of the Facebook user making the request. A nil value indicates a request that requires no token; to use the active session pass [FBSession activeSession].

restMethod

A valid REST API method.

parameters

The parameters for the request. A value of nil sends only the automatically handled parameters, for example, the access token. The default is nil.

HTTPMethod

The HTTP method to use for the request. The default is value of nil implies a GET.

- (instancetype)
initWithSession: (FBSession *)session
restMethod: (NSString *)restMethod
parameters: (NSDictionary *)parameters
HTTPMethod: (NSString *)HTTPMethod;
Discussion:

Prefer to use graph requests instead of this where possible.

Note that this only sets properties on the FBRequest.

To send the request, initialize a FBRequestConnection, add this request, and send [FBRequestConnection start]. See other methods on this class for shortcuts to simplify this process.

Declared In: FBRequest.h
overrideVersionPartWith:

Overrides the default version for a single request

ParameterDescription
version

This is a string in the form @"v2.0" which will be used for the version part of an API path

- (void) overrideVersionPartWith:(NSString *)version;
Discussion:

The SDK automatically prepends a version part, such as "v2.0" to API paths in order to simplify API versioning for applications. Sometimes it is preferable to explicitly set the version for a request, which can be accomplished in one of two ways. The first is to call this method and set an override version part. The second is approach is to include the version part in the api path, for example @"v2.0/me/friends"

Declared In: FBRequest.h
startWithCompletionHandler:

Starts a connection to the Facebook API.

ParameterDescription
handler

The handler block to call when the request completes with a success, error, or cancel action. The handler will be invoked on the main thread.

- (FBRequestConnection *) startWithCompletionHandler:(FBRequestHandler)handler;
Discussion:

This is used to start an API call to Facebook and call the block when the request completes with a success, error, or cancel.

Declared In: FBRequest.h
Constants
FBGraphBasePath
FBSDK_EXTER N NSString *const FBGraphBasePath __attribute__((deprecated));
Discussion:

The base URL used for graph requests

Declared In: FBRequest.h
Typedefs
FBRequestState

Deprecated - do not use in new code.

typedef NSUInteger FBRequestState __attribute__((deprecated));
Discussion:

FBRequestState is retained from earlier versions of the SDK to give existing apps time to remove dependency on this.

Declared In: FBRequest.h