Using REST APIs

Coding REST Interactions

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 for RestClient 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 the ClientManager.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 appropriate RestRequest static getter function such as RestRequest.getRequestForCreate().

  Important

• RestResponse—Contains the response content in the requested format. The RestRequest class creates RestResponse instances and returns them to your app through your implementation of the RestClient.AsyncRequestCallback interface.

Here’s the basic procedure for using the REST classes on a UI thread:

1. Create an instance of ClientManager.

   1. Use the SalesforceSDKManager.getInstance().getAccountType() method to obtain the value to pass as the second argument of the ClientManager constructor.

   2. For the LoginOptions parameter of the ClientManager constructor, call SalesforceSDKManager.getInstance().getLoginOptions().

2. Implement the ClientManager.RestClientCallback interface.

3. Call ClientManager.getRestClient() to obtain a RestClient instance, passing it an instance of your RestClientCallback implementation. The following code implements and instantiates RestClientCallback inline.

   Kotlin

   1val accountType = SalesforceSDKManager.getInstance().accountType
   2
   3val loginOptions = SalesforceSDKManager.getInstance().loginOptions
   4// Get a rest client
   5ClientManager(this, accountType, loginOptions,
   6        SalesforceSDKManager.getInstance().shouldLogoutWhenTokenRevoked()).
   7            getRestClient(this, object : RestClientCallback() {
   8    fun authenticatedRestClient(client: RestClient?) {
   9        if (client == null) {
   10            SalesforceSDKManager.getInstance().logout(this@MainActivity)
   11            return
   12        }
   13        // Cache the returned client
   14        this@MainActivity.client = client
   15    }
   16}
   17)

   Java

   1String accountType = 
   2    SalesforceSDKManager.getInstance().getAccountType();
   3   
   4LoginOptions loginOptions = 
   5    SalesforceSDKManager.getInstance().getLoginOptions();
   6// Get a rest client
   7new ClientManager(this, accountType, loginOptions, 
   8   SalesforceSDKManager.getInstance().
   9   shouldLogoutWhenTokenRevoked()).
   10   getRestClient(this, new RestClientCallback() {
   11      @Override
   12      public void 
   13      authenticatedRestClient(RestClient client) {
   14         if (client == null) {
   15            SalesforceSDKManager.getInstance().
   16               logout(MyActivity.this);
   17            return;
   18         }
   19         // Cache the returned client
   20         MyActivity.this.client = client; 
   21      }   
   22   }
   23);

4. Call a static RestRequest() getter method to obtain the appropriate RestRequest object for your needs. For example, to get a description of a Salesforce object:
   1final RestRequest request = RestRequest.getRequestForDescribe(apiVersion, objectType);

5. Pass the RestRequest object you obtained in the previous step to RestClient.sendAsync() or RestClient.sendSync(). If you’re on a UI thread and therefore calling sendAsync():
   1. Implement the ClientManager.AsyncRequestCallback interface.
   2. Pass an instance of your implementation to the sendAsync() method.
   3. Receive the formatted response through your ASyncRequestCallback.onSuccess() method. Before using the response, double-check that it’s valid by calling RestResponse.isSuccess().

The following code implements and instantiates AsyncRequestCallback inline.

Kotlin

1private fun sendFromUIThread(restRequest: RestRequest) {
2    client.sendAsync(restRequest, object : AsyncRequestCallback {
3        private val start = System.nanoTime()
4        override fun onSuccess(request: RestRequest, result: RestResponse) {
5            // Consume before going back to main thread
6            // Not required if you don't do main (UI) thread tasks here
7            result.consumeQuietly()
8            runOnUiThread {
9                // Network component doesn’t report app layer status.
10                // Use the Mobile SDK RestResponse.isSuccess() method to check
11                // whether the REST request itself succeeded.
12                if (result.isSuccess) {
13                    try {
14                        // Do something with the result
15                    } catch (e: Exception) {
16                        printException(e)
17                    }
18
19                    EventsObservable.get().notifyEvent(EventType.RenditionComplete)
20                }
21            }
22        }
23
24        override fun onError(exception: Exception) {
25            printException(exception)
26            EventsObservable.get().notifyEvent(EventType.RenditionComplete)
27        }
28    })
29}

Java

1private void sendFromUIThread(RestRequest restRequest) {
2    client.sendAsync(restRequest, new AsyncRequestCallback() {
3        private long start = System.nanoTime(); 
4        @Override
5        public void onSuccess(RestRequest request, final RestResponse result) {
6        	// Consume before going back to main thread
7        	// Not required if you don't do main (UI) thread tasks here
8        	result.consumeQuietly();
9        	runOnUiThread(new Runnable() {
10                @Override
11                public void run() {
12                    // Network component doesn’t report app layer status.
13                    // Use the Mobile SDK RestResponse.isSuccess() method to check  
14                    // whether the REST request itself succeeded.
15                    if (result.isSuccess()) {
16                        try {
17                            // Do something with the result
18                        }
19                        catch (Exception e) {
20                            printException(e);
21                        }
22                        EventsObservable.get().notifyEvent(EventType.RenditionComplete);
23                    }
24                }
25            });
26        }
27        @Override
28        public void onError(Exception exception)
29        {
30            printException(exception);
31            EventsObservable.get().notifyEvent(EventType.RenditionComplete); 
32        }
33    });
34}

If you’re calling the sendSync() method from a service, use the same procedure with the following changes.

1. To obtain a RestClient instance call ClientManager.peekRestClient() instead of ClientManager.getRestClient().

2. Retrieve your formatted REST response from the sendSync() method’s return value.

Checking REST Response Status

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.