SFRestAPI Class Reference

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 an SFOAuthCoordinator after a successful OAuth authentication with Salesforce, by calling [[SFRestAPI sharedInstance] setCoordinator:coordinator];

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

After initialization, the singleton SFRestAPI can be accessed using [SFRestAPI sharedInstance].

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

Note: If you opt to build an SFRestRequest manually, you should be aware that send:delegate: expects that if the request.path does not begin with the request.endpoint prefix, it will add the request.endpoint prefix (kSFDefaultRestEndpoint by default) to the request path.

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.

This category assists with creating SOQL and SOSL queries.

Example SOQL usage:

NSString *soqlQuery = [SFRestAPI SOQLQueryWithFields:[NSArray arrayWithObjects:@“Id”, @“Name”, @“Company”, @“Status”, nil] sObject:@“Lead” where:nil limit:10];

Example SOSL usage:

NSString *soslQuery = [SFRestAPI SOSLSearchWithSearchTerm:@“all of these will be escaped:~{]”

                          objectScope:[NSDictionary dictionaryWithObject:@"WHERE isactive=true ORDER BY lastname asc limit 5"
                                                                  forKey:@"User"]];

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 “v23.0”)
property
+ sharedInstance
Returns the singleton instance of SFRestAPI After a successful oauth login with an SFOAuthCoordinator, you should set it as the coordinator property of this instance.
– send:delegate:
Sends a REST request to the Salesforce server and invokes the appropriate delegate method.

SFRestRequest factory methods

– 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.
– requestForResources
Returns an SFRestRequest which lists available resources for the client’s API version, including resource name and URI.
– requestForDescribeGlobal
Returns an SFRestRequest which lists the available objects and their metadata for your organization’s data.
– requestForMetadataWithObjectType:
Returns an SFRestRequest which Describes the individual metadata for the specified object.
– requestForDescribeWithObjectType:
Returns an SFRestRequest which completely describes the individual metadata at all levels for the specified object.
– requestForRetrieveWithObjectType:objectId:fieldList:
Returns an SFRestRequest which retrieves field values for a record of the given type.
– requestForCreateWithObjectType:fields:
Returns an SFRestRequest which creates a new record of the given type.
– requestForUpsertWithObjectType:externalIdField:externalId:fields:
Returns an SFRestRequest which creates or updates record of the given type, based on the given external ID.
– requestForUpdateWithObjectType:objectId:fields:
Returns an SFRestRequest which updates field values on a record of the given type.
– requestForDeleteWithObjectType:objectId:
Returns an SFRestRequest which deletes a record of the given type.
– requestForQuery:
Returns an SFRestRequest which executes the specified SOQL query.
– requestForSearch:
Returns an SFRestRequest which executes the specified SOSL search.

Other utility methods

+ userAgentString
Provides the User-Agent string used by the SDK

QueryBuilder Methods

+ sanitizeSOSLSearchTerm:
The search term to be sanitized.
+ SOSLSearchWithSearchTerm:objectScope:
Generate a SOSL search.
+ SOSLSearchWithSearchTerm:fieldScope:objectScope:limit:
Generate a SOSL search.
+ SOQLQueryWithFields:sObject:where:limit:
Generate a SOQL query.
+ SOQLQueryWithFields:sObject:where:groupBy:having:orderBy:limit:
Generate a SOQL query.

Blocks Methods

– sendRESTRequest:failBlock:completeBlock:
Send a request you’ve already built, using blocks to return status.
– performSOQLQuery:failBlock:completeBlock:
Executes a SOQL query.
– performSOSLSearch:failBlock:completeBlock:
Executes a SOSL search.
– performDescribeGlobalWithFailBlock:completeBlock:
Executes a global describe.
– performDescribeWithObjectType:failBlock:completeBlock:
Executes a describe on a single sObject.
– performMetadataWithObjectType:failBlock:completeBlock:
Executes a metadata describe on a single sObject.
– performRetrieveWithObjectType:objectId:fieldList:failBlock:completeBlock:
Executes a retrieve for a single record.
– performUpdateWithObjectType:objectId:fields:failBlock:completeBlock:
Executes a DML update for a single record.
– performUpsertWithObjectType:externalIdField:externalId:fields:failBlock:completeBlock:
Executes a DML upsert for a single record.
– performDeleteWithObjectType:objectId:failBlock:completeBlock:
Executes a DML delete on a single record
– performCreateWithObjectType:fields:failBlock:completeBlock:
Executes a DML insert.
– performRequestForResourcesWithFailBlock:completeBlock:
Executes a request to list REST API resources
– performRequestForVersionsWithFailBlock:completeBlock:
Executes a request to list REST API versions

Properties

apiVersion

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

@property (nonatomic, strong) 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 “v23.0”)

Declared In

SFRestAPI.h

Class Methods

SOQLQueryWithFields:sObject:where:groupBy:having:orderBy:limit:

Generate a SOQL query.

+ (NSString *)SOQLQueryWithFields:(NSArray *)fields sObject:(NSString *)sObject where:(NSString *)where groupBy:(NSArray *)groupBy having:(NSString *)having orderBy:(NSArray *)orderBy limit:(NSInteger)limit

Parameters

fields

NSArray of fields to select

sObject

object to query

where

nil OR where clause

groupBy

nil OR NSArray of strings, each string is an individual group by clause

having

nil OR having clause

orderBy

nil OR NSArray of strings, each string is an individual order by clause

limit

limit count, or 0 for no limit (for use with query locators)

Discussion

Generate a SOQL query.

Declared In

SFRestAPI+QueryBuilder.h

SOQLQueryWithFields:sObject:where:limit:

Generate a SOQL query.

+ (NSString *)SOQLQueryWithFields:(NSArray *)fields sObject:(NSString *)sObject where:(NSString *)where limit:(NSInteger)limit

Parameters

fields

NSArray of fields to select

sObject

object to query

where

nil OR where clause

limit

limit count, or 0 for no limit (for use with query locators)

Discussion

Generate a SOQL query.

Declared In

SFRestAPI+QueryBuilder.h

SOSLSearchWithSearchTerm:fieldScope:objectScope:limit:

Generate a SOSL search.

+ (NSString *)SOSLSearchWithSearchTerm:(NSString *)term fieldScope:(NSString *)fieldScope objectScope:(NSDictionary *)objectScope limit:(NSInteger)limit

Parameters

term

the search term. This is sanitized for proper characters

fieldScope

nil OR the SOSL scope, e.g. “IN ALL FIELDS”. if nil, defaults to “IN NAME FIELDS”

objectScope

nil to search all searchable objects, or a dictionary where each key is an sObject name and each value is a string with the fieldlist and (optional) where, order by, and limit clause for that object. or NSNull to not specify any fields/clauses for that object

limit

overall search limit (max 200)

Discussion

Generate a SOSL search.

Declared In

SFRestAPI+QueryBuilder.h

SOSLSearchWithSearchTerm:objectScope:

Generate a SOSL search.

+ (NSString *)SOSLSearchWithSearchTerm:(NSString *)term objectScope:(NSDictionary *)objectScope

Parameters

term

the search term. This is sanitized for proper characters

objectScope

nil to search all searchable objects, or a dictionary where each key is an sObject name and each value is a string with the fieldlist and (optional) where, order by, and limit clause for that object. or NSNull to not specify any fields/clauses for that object

Discussion

Generate a SOSL search.

Declared In

SFRestAPI+QueryBuilder.h

sanitizeSOSLSearchTerm:

The search term to be sanitized.

+ (NSString *)sanitizeSOSLSearchTerm:(NSString *)searchTerm

Parameters

searchTerm: The search term to be sanitized.

Return Value

SOSL-safe version of search term

Declared In

SFRestAPI+QueryBuilder.h

sharedInstance

Returns the singleton instance of SFRestAPI After a successful oauth login with an SFOAuthCoordinator, you should set it as the coordinator property of this instance.

+ (SFRestAPI *)sharedInstance

Discussion

Returns the singleton instance of SFRestAPI After a successful oauth login with an SFOAuthCoordinator, you should set it as the coordinator property of this instance.

Declared In

SFRestAPI.h

userAgentString

Provides the User-Agent string used by the SDK

+ (NSString *)userAgentString

Discussion

Provides the User-Agent string used by the SDK

Declared In

SFRestAPI.h

Instance Methods

performCreateWithObjectType:fields:failBlock:completeBlock:

Executes a DML insert.

- (SFRestRequest *)performCreateWithObjectType:(NSString *)objectType fields:(NSDictionary *)fields failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

objectType: the API name of the object to insert

fields: a dictionary of fields to use in the insert.

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a DML insert.

Declared In

SFRestAPI+Blocks.h

performDeleteWithObjectType:objectId:failBlock:completeBlock:

Executes a DML delete on a single record

- (SFRestRequest *)performDeleteWithObjectType:(NSString *)objectType objectId:(NSString *)objectId failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

objectType: the API name of the object to delete

objectId: the actual Id of the record to delete

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a DML delete on a single record

Declared In

SFRestAPI+Blocks.h

performDescribeGlobalWithFailBlock:completeBlock:

Executes a global describe.

- (SFRestRequest *)performDescribeGlobalWithFailBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a global describe.

Declared In

SFRestAPI+Blocks.h

performDescribeWithObjectType:failBlock:completeBlock:

Executes a describe on a single sObject.

- (SFRestRequest *)performDescribeWithObjectType:(NSString *)objectType failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

objectType: the API name of the object to describe.

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a describe on a single sObject.

Declared In

SFRestAPI+Blocks.h

performMetadataWithObjectType:failBlock:completeBlock:

Executes a metadata describe on a single sObject.

- (SFRestRequest *)performMetadataWithObjectType:(NSString *)objectType failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

objectType: the API name of the object to describe.

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a metadata describe on a single sObject.

Declared In

SFRestAPI+Blocks.h

performRequestForResourcesWithFailBlock:completeBlock:

Executes a request to list REST API resources

- (SFRestRequest *)performRequestForResourcesWithFailBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a request to list REST API resources

Declared In

SFRestAPI+Blocks.h

performRequestForVersionsWithFailBlock:completeBlock:

Executes a request to list REST API versions

- (SFRestRequest *)performRequestForVersionsWithFailBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a request to list REST API versions

Declared In

SFRestAPI+Blocks.h

performRetrieveWithObjectType:objectId:fieldList:failBlock:completeBlock:

Executes a retrieve for a single record.

- (SFRestRequest *)performRetrieveWithObjectType:(NSString *)objectType objectId:(NSString *)objectId fieldList:(NSArray *)fieldList failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

objectType: the API name of the object to retrieve

objectId: the record ID of the record to retrieve

fieldList: an array of fields on this record to retrieve

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a retrieve for a single record.

Declared In

SFRestAPI+Blocks.h

performSOQLQuery:failBlock:completeBlock:

Executes a SOQL query.

- (SFRestRequest *)performSOQLQuery:(NSString *)query failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

query: the SOQL query to be executed

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a SOQL query.

Declared In

SFRestAPI+Blocks.h

performSOSLSearch:failBlock:completeBlock:

Executes a SOSL search.

- (SFRestRequest *)performSOSLSearch:(NSString *)search failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestArrayResponseBlock)completeBlock

Parameters

search: the SOSL search to be executed

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a SOSL search.

Declared In

SFRestAPI+Blocks.h

performUpdateWithObjectType:objectId:fields:failBlock:completeBlock:

Executes a DML update for a single record.

- (SFRestRequest *)performUpdateWithObjectType:(NSString *)objectType objectId:(NSString *)objectId fields:(NSDictionary *)fields failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

objectType: the API name of the object to update

objectId: the record ID of the object

fields: a dictionary of fields to update.

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a DML update for a single record.

Declared In

SFRestAPI+Blocks.h

performUpsertWithObjectType:externalIdField:externalId:fields:failBlock:completeBlock:

Executes a DML upsert for a single record.

- (SFRestRequest *)performUpsertWithObjectType:(NSString *)objectType externalIdField:(NSString *)externalIdField externalId:(NSString *)externalId fields:(NSDictionary *)fields failBlock:(SFRestFailBlock)failBlock completeBlock:(SFRestDictionaryResponseBlock)completeBlock

Parameters

objectType: the API name of the object to update

externalIdField: the API name of the external ID field to use for updating

externalId: the actual external Id

fields: a dictionary of fields to include in the upsert

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Return Value

the newly sent SFRestRequest

Discussion

Executes a DML upsert for a single record.

Declared In

SFRestAPI+Blocks.h

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. This overwrites the delegate property of the request.

Discussion

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

Declared In

SFRestAPI.h

sendRESTRequest:failBlock:completeBlock:

Send a request you’ve already built, using blocks to return status.

- (void)sendRESTRequest:(SFRestRequest *)request failBlock:(SFRestFailBlock)failBlock completeBlock:(id)completeBlock

Parameters

request: the SFRestRequest to be sent

failBlock: the block to be executed when the request fails (timeout, cancel, or error)

completeBlock: the block to be executed when the request successfully completes

Discussion

Send a request you’ve already built, using blocks to return status.

Declared In

SFRestAPI+Blocks.h