Using REST APIs
To query, describe, create, or update data from a Salesforce org, Mobile SDK apps call Salesforce REST APIs. Salesforce REST APIs honor SOQL and SOSL strings and can accept and return data in either JSON or XML format. Mobile SDK wraps standard Salesforce REST requests in methods that handle the low-level HTTP configuration for you. For other Salesforce APIs, Mobile SDK provides methods for manually creating a custom request object and receiving the response. You can even use Mobile SDK REST API methods to make unauthenticated and external API calls.
Salesforce supports an ever-growing variety of REST APIs. For an overview of our offerings, see Which API Do I Use? in Salesforce Help. For information on standard REST APIs, see REST API Developer Guide.
With Android native apps, you do minimal coding to access Salesforce data through REST calls. The classes in the com.salesforce.androidsdk.rest
package initialize the communication channels and encapsulate low-level HTTP plumbing. These classes, all of which are implemented by Mobile SDK, include:
-
ClientManager
—Serves as a factory forRestClient
instances. It also handles account logins and handshakes with the Salesforce server. -
RestClient
—Handles protocol for sending REST API requests to the Salesforce server.Don’t directly create instances of
RestClient
. Instead, call theClientManager.getRestClient()
method. -
RestRequest
—Represents REST API requests formatted from the data you provide. Also serves as a factory for instances of itself.Don’t directly create instances of
RestRequest
. Instead, call an appropriateRestRequest
static getter function such asRestRequest.getRequestForCreate()
. -
RestResponse
—Contains the response content in the requested format. TheRestRequest
class createsRestResponse
instances and returns them to your app through your implementation of theRestClient.AsyncRequestCallback
interface.
Here’s the basic procedure for using the REST classes on a UI thread:
-
Create an instance of
ClientManager
.-
Use the
SalesforceSDKManager.getInstance().getAccountType()
method to obtain the value to pass as the second argument of theClientManager
constructor. -
For the
LoginOptions
parameter of theClientManager
constructor, callSalesforceSDKManager.getInstance().getLoginOptions()
.
-
-
Implement the
ClientManager.RestClientCallback
interface. -
Call
ClientManager.getRestClient()
to obtain aRestClient
instance, passing it an instance of yourRestClientCallback
implementation. The following code implements and instantiatesRestClientCallback
inline.- Kotlin
- Java
-
Call a static
RestRequest()
getter method to obtain the appropriateRestRequest
object for your needs. For example, to get a description of a Salesforce object: -
Pass the
RestRequest
object you obtained in the previous step toRestClient.sendAsync()
orRestClient.sendSync()
. If you’re on a UI thread and therefore callingsendAsync()
:- Implement the
ClientManager.AsyncRequestCallback
interface. - Pass an instance of your implementation to the
sendAsync()
method. - Receive the formatted response through your
ASyncRequestCallback.onSuccess()
method. Before using the response, double-check that it’s valid by callingRestResponse.isSuccess()
.
- Implement the
The following code implements and instantiates AsyncRequestCallback
inline.
- Kotlin
- Java
If you’re calling the sendSync()
method from a service, use the same procedure with the following changes.
- To obtain a
RestClient
instance callClientManager.peekRestClient()
instead ofClientManager.getRestClient()
. - Retrieve your formatted REST response from the
sendSync()
method’s return value.
A REST response arriving at your app’s onSuccess() callback method indicates only that the network call didn’t fail. This high-level status doesn’t factor in app-level success or failure.
In Mobile SDK for Android, the RestResponse
object wraps the underlying okHttp3.Response
. To help you code more defensively, RestResponse
provides the following convenience methods for inspecting response details.- public isSuccess()
public static boolean isSuccess(int statusCode)
Returns
true
if the HTTP response status code or the given code is between 200 and 299, indicating app-level success.public int getStatusCode()
Returns the response status code.
public String getContentType()
Returns the
content-type
header, if found.public Map<String, List<String>> getAllHeaders()
Returns all headers associated with this response.
public Response getRawResponse()
Returns the underlying
okHttp3.Response
object.