New Client API Model in Google Play Services

By Magnus Hyttsten, Google Developer Relations

Google Play services 4.2 has now been rolled out to the world, and it’s packed with much-anticipated features such as the brand new Cast API and the updated Drive API.

In addition to these blockbuster announcements, we are also launching a slightly less visible but equally important new API — a new way to connect client APIs and manage API requests. As with the initial Drive API, these changes were available as a developer preview in earlier releases of Google Play services. We're now happy to graduate those APIs to fully supported and official.

In this post we'll take a look at the new Google Play services client APIs and what they mean for your apps — for details be sure to read Accessing Google Play services and the API reference documentation.

Connecting Client APIs

The client connection model has now been unified for all the APIs. As you may recall, you were previously required to use separate client classes for each API you wanted to use, for example: PlusClient, GamesClient, etc. Instead, you should now use GoogleApiClient, which allows you to connect to multiple APIs using a single call. This has great advantages such as:

• Simplicity—The onConnected() method will be called once, and only when connectivity to all the client APIs you are using have been established. This means you do not have to intercept multiple callbacks, one for each API connected, which simplifies the code and state management.
• Improved user experience—With this design, Google Play services knows about everything your app needs up front. All APIs, all scopes, the works. This means that we can take care of the user consents at once, creating a single consolidated user experience for all the APIs. No more sign-in mid-process terminations, partial state management, etc.

Below is an example of establishing a connection the Google+ and Drive APIs. To see the reference information for this new client connection model, you should check out the com.google.android.gms.common.api package.

@Override
protected void onCreate(Bundle b) {
    super.onCreate(b);

    // Builds single client object that connects to Drive and Google+
    mClient = new GoogleApiClient.Builder(this)
            .addApi(Drive.API)
            .addScope(Drive.SCOPE_FILE)
            .addApi(Plus.API, plusOptions)
            .addScope(Plus.SCOPE_PLUS_LOGIN)
            .addConnectionCallbacks(this)
            .addOnConnectionFailedListener(this)
            .build();      
}

@Override
protected void onStart() {
    super.onStart();

    // Connect to Drive and Google+
    mClient.connect();
}

@Override
protected void onConnected(Bundle connectionHint) {
    // All clients are connected
    startRockAndRoll();
}

@Override
protected void onConnectionFailed(ConnectionResult result) {
    // At least one of the API client connect attempts failed
    // No client is connected
    ...
}

Enqueuing API Calls

Another new feature is enqueuing of API calls, which allows you to call read methods before the API clients are connected. This means you can issue these calls up front, for example in onStart/onResume, rather than having to wait and issue them in different callback methods. This is something which will greatly simplify code if your app requires data to be read when it is started. Here is an example of where a call like this can be placed:

@Override
protected void onStart() {
    super.onStart();
    mClient.connect();
}

@Override
protected void onResume() {
    super.onResume();

    // Enqueue operation.
    // This operation will be enqueued and issued once the API clients are connected.
    // Only API retrieval operations are allowed.
    // Asynchronous callback required to not lock the UI thread.
    Plus.PeopleApi.load(mClient, “me”, “you”, “that”).setResultCallback(this);
}

Supporting both Asynchronous and Synchronous Execution

With this release of Google Play services, you now have the option to specify if an API call should execute asynchronously (you will receive a callback once it is finished), or synchronously (the thread will block until the operation has completed). This is achieved by using the classes PendingResult, Result, and Status in the com.google.android.gms.common.api package.

In practice, this means that API operations will return an instance of PendingResult, and you can choose if you want the method to execute asynchronously using setResultCallback or synchronously using await. The following example demonstrates how to synchronously retrieve the metadata for a file and then clear any starred flag setting:

// Must be run in a background task and not on UI thread
new AsyncTask <DriveFile, Void, Void> {
    protected void doInBackground(DriveFile driveFile) {

        // Get the metadata synchronously
        MetaDataResult mdGetResult = driveFile.getMetadata(mClient).await();
        if (!mdGetResult.isSuccess()) {
            // Handle error
        }

        MetaData md = mdGetResult.getMetadata()
        // Perform operations based on metadata

        // Update the meta data, unconditionally clear the starred flag        
        MetaDataChangeSet mdCS = new MetadataChangeSet.Builder()
            .setStarred(false)
            .build();

        MetaDataResult mdUpdateResult =driveFile.updateMetaData(mClient,mdCS).await();
        if (!mdUpdateResult.isSuccess()) {
            // Handle error
        }

        … // continue doing other things synchronously
}).execute(fileName);

It should be stressed though that the old best practice rule — do not block the UI thread — is still in effect. This means that the execution of this sequence of API calls described above must be performed from a background thread, potentially by using AsyncTask as in the example above.

Moving your apps to the new client API

We believe these changes will make it easier for you to build with Google Play services in your apps. For those of you using the older clients, we recommend refactoring your code as soon as possible to take advantage of these features. Apps deployed using the old client APIs will continue to work since these changes do not break binary compatibility, but the old APIs are now deprecated and we'll be removing them over time.

That’s it for this time. Google Play services allows Google to provide you with new APIs and features faster than ever, and with the capabilities described in this post, you now have a generic way of using multiple client APIs and executing API calls. Make sure to check out the video below for a closer look at the new client APIs.

To learn more about Google Play services and the APIs available to you through it, visit the Google Services area of the Android Developers site. Details on the APIs are available in the API reference.

For information about getting started with Google Play services APIs, see Set Up Google Play Services SDK