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 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[...]
methodby 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 therequestForQuery:
, or trying to update a non-existent object). In this case,request:didFailLoadWithError:
is called on theSFRestDelegate
. The error passed will have an error domain ofkSFRestErrorDomain
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 secondSFRestRequest
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 theSFRestDelegate
. The error passed will have an error domain ofkSFOAuthErrorDomain
. 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 theSFRestDelegate
. The error passed will be a standardRestKit
error with an error domain ofRKRestKitErrorDomain
.
Tasks
Other Methods
-
apiVersion
The REST API version used for all the calls. This could be “v21.0”, “v22.0”… The default value is
propertykSFRestDefaultAPIVersion
(currently “v22.0”) -
+ 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
-
– 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.
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
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.
See Also
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.
See Also
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.
See Also
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.
See Also
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.
See Also
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.
See Also
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.
See Also
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