Inherits from NSObject
Declared in SFRestAPI.h

Overview

Main class used to issue REST requests to the standard Force.com REST API.

See the Force.com REST API Developer’s Guide for more information regarding the Force.com REST API.

Initialization

This class is initialized with APIWithCoordinator: after a successful OAuth authentication with Salesforce. After initialization, a singletion object is created, which can then be accessed using [SFRestAPI sharedInstance].

The initialization is usually done in the method oauthCoordinatorDidAuthenticate:coordinator: of the class handling the OAuth connection.

Here is a full example (in the ApplicationDelegate class for instance):

// Re-acquire an oauth token when the app becomes active
- (void)applicationDidBecomeActive:(UIApplication *)application
    SFOAuthCredentials *credentials = [[[SFOAuthCredentials alloc]
                                        initWithIdentifier:@"your_oauth_consumer_key"] autorelease];
    credentials.redirectUri = @"your_oauth_redirect_uri";

    self.coordinator = [[[SFOAuthCoordinator alloc]
                         initWithCredentials:credentials] autorelease];
    self.coordinator.delegate = self;
    [self.coordinator authenticate];
}

#pragma mark - SFOAuthCoordinatorDelegate

// Display oauth UIWebView on main UIViewController
- (void)oauthCoordinator:(SFOAuthCoordinator *)coordinator 
didBeginAuthenticationWithView:(UIWebView *)view {
    [self.window addSubview:view];
}

// The user is now logged in.
// The SFRestAPI can now be initialized
- (void)oauthCoordinatorDidAuthenticate:(SFOAuthCoordinator *)coordinator {
    [coordinator.view removeFromSuperview];
    [SFRestAPI APIWithCoordinator:self.coordinator];
    // ...
}

- (void)oauthCoordinator:(SFOAuthCoordinator *)coordinator
didFailWithError:(NSError *)error {
    [coordinator.view removeFromSuperview];
    NSLog(@"oauthCoordinator:didFailWithError: %@", error);
    // maybe display an Alert and retry by calling [self.coordinator authenticate];
}

Sending requests

Sending a request is done using send:delegate:. The class sending the request has to conform to the protocol SFRestDelegate.

A request can be obtained in two different ways:

  • by calling the appropriate requestFor[...] method

  • by building the SFRestRequest manually

For example, this sample code calls the requestForDescribeWithObjectType: method to return information about the Account object.

- (void)describeAccount {
    SFRestRequest *request = [[SFRestAPI sharedInstance]
                              requestForDescribeWithObjectType:@"Account"];
    [[SFRestAPI sharedInstance] send:request delegate:self];
}

#pragma mark - SFRestDelegate

- (void)request:(SFRestRequest *)request didLoadResponse:(id)jsonResponse {
    NSDictionary *dict = (NSDictionary *)jsonResponse;
    NSArray *fields = (NSArray *)[dict objectForKey:@"fields"];
    // ...
}

- (void)request:(SFRestRequest*)request didFailLoadWithError:(NSError*)error {
    // handle error
}

- (void)requestDidCancelLoad:(SFRestRequest *)request {
    // handle error
}

- (void)requestDidTimeout:(SFRestRequest *)request {
    // handle error
}

Error handling

When sending a SFRestRequest, you may encounter one of these errors:

  • The request parameters could be invalid (for instance, passing nil to the requestForQuery:, or trying to update a non-existent object). In this case, request:didFailLoadWithError: is called on the SFRestDelegate. The error passed will have an error domain of kSFRestErrorDomain

  • The oauth access token (session ID) could have expired. In this case, the framework tries to acquire another access token and re-issue the SFRestRequest. This is all done transparently and the appropriate delegate method is called once the second SFRestRequest returns.

  • Requesting a new access token (session ID) could fail (if the access token has expired and the OAuth refresh token is invalid). In this case, request:didFailLoadWithError: will be called on the SFRestDelegate. The error passed will have an error domain of kSFOAuthErrorDomain. Note that this is a very rare case.

  • The underlying HTTP request could fail (Salesforce server is innaccessible…) In this case, request:didFailLoadWithError: is called on the SFRestDelegate. The error passed will be a standard RestKit error with an error domain of RKRestKitErrorDomain.

Tasks

Other Methods

  •   apiVersion

    The REST API version used for all the calls. This could be “v21.0”, “v22.0”… The default value is kSFRestDefaultAPIVersion (currently “v22.0”)

    property
  • + sharedInstance

    Returns the configured singleton instance of SFRestAPI

  • + APIWithCoordinator:

    Builds a new SFResstApi object with the supplied OAuth credentials.

  • – send:delegate:

    Sends a REST request to the Salesforce server and invokes the appropriate delegate method.

SFRestRequest factory methods

Properties

apiVersion

The REST API version used for all the calls. This could be “v21.0”, “v22.0”… The default value is kSFRestDefaultAPIVersion (currently “v22.0”)

@property (nonatomic, retain) NSString *apiVersion

Discussion

The REST API version used for all the calls. This could be “v21.0”, “v22.0”… The default value is kSFRestDefaultAPIVersion (currently “v22.0”)

Declared In

SFRestAPI.h

Class Methods

APIWithCoordinator:

Builds a new SFResstApi object with the supplied OAuth credentials.

+ (id)APIWithCoordinator:(SFOAuthCoordinator *)coordinator

Discussion

Builds a new SFResstApi object with the supplied OAuth credentials.

You don’t need to keep a reference to this class. Once the class is created, it gets assigned to the singleton instance sharedInstance and can be retrieved by calling [SFRestAPI sharedInstance]

This should only be called after a successful OAuth authentication with Salesforce.

See Also

Declared In

SFRestAPI.h

sharedInstance

Returns the configured singleton instance of SFRestAPI

+ (SFRestAPI *)sharedInstance

Discussion

Returns the configured singleton instance of SFRestAPI

Declared In

SFRestAPI.h

Instance Methods

requestForCreateWithObjectType:fields:

Returns an SFRestRequest which creates a new record of the given type.

- (SFRestRequest *)requestForCreateWithObjectType:(NSString *)objectType fields:(NSDictionary *)fields

Parameters

objectType

object type; for example, “Account”

fields

an NSDictionary containing initial field names and values for the record, for example, {Name: “salesforce.com”, TickerSymbol: “CRM”}

Discussion

Returns an SFRestRequest which creates a new record of the given type.

Declared In

SFRestAPI.h

requestForDeleteWithObjectType:objectId:

Returns an SFRestRequest which deletes a record of the given type.

- (SFRestRequest *)requestForDeleteWithObjectType:(NSString *)objectType objectId:(NSString *)objectId

Parameters

objectType

object type; for example, “Account”

objectId

the record’s object ID

Discussion

Returns an SFRestRequest which deletes a record of the given type.

Declared In

SFRestAPI.h

requestForDescribeGlobal

Returns an SFRestRequest which lists the available objects and their metadata for your organization’s data.

- (SFRestRequest *)requestForDescribeGlobal

Discussion

Returns an SFRestRequest which lists the available objects and their metadata for your organization’s data.

Declared In

SFRestAPI.h

requestForDescribeWithObjectType:

Returns an SFRestRequest which completely describes the individual metadata at all levels for the specified object.

- (SFRestRequest *)requestForDescribeWithObjectType:(NSString *)objectType

Parameters

objectType

object type; for example, “Account”

Discussion

Returns an SFRestRequest which completely describes the individual metadata at all levels for the specified object.

Declared In

SFRestAPI.h

requestForMetadataWithObjectType:

Returns an SFRestRequest which Describes the individual metadata for the specified object.

- (SFRestRequest *)requestForMetadataWithObjectType:(NSString *)objectType

Parameters

objectType

object type; for example, “Account”

Discussion

Returns an SFRestRequest which Describes the individual metadata for the specified object.

Declared In

SFRestAPI.h

requestForQuery:

Returns an SFRestRequest which executes the specified SOQL query.

- (SFRestRequest *)requestForQuery:(NSString *)soql

Parameters

soql

a string containing the query to execute – for example, “SELECT Id, Name from Account ORDER BY Name LIMIT 20”

Discussion

Returns an SFRestRequest which executes the specified SOQL query.

Declared In

SFRestAPI.h

requestForResources

Returns an SFRestRequest which lists available resources for the client’s API version, including resource name and URI.

- (SFRestRequest *)requestForResources

Discussion

Returns an SFRestRequest which lists available resources for the client’s API version, including resource name and URI.

Declared In

SFRestAPI.h

requestForRetrieveWithObjectType:objectId:fieldList:

Returns an SFRestRequest which retrieves field values for a record of the given type.

- (SFRestRequest *)requestForRetrieveWithObjectType:(NSString *)objectType objectId:(NSString *)objectId fieldList:(NSString *)fieldList

Parameters

objectType

object type; for example, “Account”

objectId

the record’s object ID

fieldList

comma-separated list of fields for which to return values; for example, “Name,Industry,TickerSymbol”. Pass nil to retrieve all the fields.

Discussion

Returns an SFRestRequest which retrieves field values for a record of the given type.

Declared In

SFRestAPI.h

requestForSearch:

Returns an SFRestRequest which executes the specified SOSL search.

- (SFRestRequest *)requestForSearch:(NSString *)sosl

Parameters

sosl

a string containing the search to execute – for example, “FIND {needle}”

Discussion

Returns an SFRestRequest which executes the specified SOSL search.

Declared In

SFRestAPI.h

requestForUpdateWithObjectType:objectId:fields:

Returns an SFRestRequest which updates field values on a record of the given type.

- (SFRestRequest *)requestForUpdateWithObjectType:(NSString *)objectType objectId:(NSString *)objectId fields:(NSDictionary *)fields

Parameters

objectType

object type; for example, “Account”

objectId

the record’s object ID

fields

an object containing initial field names and values for the record, for example, {Name: “salesforce.com”, TickerSymbol “CRM”}

Discussion

Returns an SFRestRequest which updates field values on a record of the given type.

Declared In

SFRestAPI.h

requestForUpsertWithObjectType:externalIdField:externalId:fields:

Returns an SFRestRequest which creates or updates record of the given type, based on the given external ID.

- (SFRestRequest *)requestForUpsertWithObjectType:(NSString *)objectType externalIdField:(NSString *)externalIdField externalId:(NSString *)externalId fields:(NSDictionary *)fields

Parameters

objectType

object type; for example, “Account”

externalIdField

external ID field name; for example, “accountMaster__c”

externalId

the record’s external ID value

fields

an NSDictionary containing field names and values for the record, for example, {Name: “salesforce.com”, TickerSymbol “CRM”}

Discussion

Returns an SFRestRequest which creates or updates record of the given type, based on the given external ID.

Declared In

SFRestAPI.h

requestForVersions

Returns an SFRestRequest which lists summary information about each Salesforce.com version currently available, including the version, label, and a link to each version’s root.

- (SFRestRequest *)requestForVersions

Discussion

Returns an SFRestRequest which lists summary information about each Salesforce.com version currently available, including the version, label, and a link to each version’s root.

Declared In

SFRestAPI.h

send:delegate:

Sends a REST request to the Salesforce server and invokes the appropriate delegate method.

- (void)send:(SFRestRequest *)request delegate:(id<SFRestDelegate>)delegate

Parameters

request

the SFRestRequest to be sent

delegate

the delegate object used when the response from the server is returned

Discussion

Sends a REST request to the Salesforce server and invokes the appropriate delegate method.

Declared In

SFRestAPI.h