My favorites | Sign in
Project Home Downloads Wiki Issues Source
Search
for
MigratingToGoogleApiJavaClient  
Migrating to Google API Client for Java
Updated Jun 6, 2012 by [email protected]

Updated information

We have changed our strategy significantly with respect to migration from gdata-java-client to google-api-java-client. Older GData APIs use XML as their underlying format. Most Google APIs have released newer versions of their APIs instead based on JSON. So in general you should wait until the API you are using switches to the new API infrastructure based on JSON, where we can provide a much better experience. Of course we cannot make any promises about when or if any specific API will do so.

For Picasa Web Albums Data API and Documents List Data API we've written samples based on google-api-java-client, and we encourage you to take a look at those samples. If you have a need for a sample for a different API, please go ahead and ask on the google-api-java-client Google group if any one has sample code they are willing to share.

Obsolete information

WARNING: the information below in this guide is obsolete.

This guide is written for existing users of the Google Data Java Client Library (a.k.a. "gdata-java-client") that wish to migrate to the Google API Client Library for Java (a.k.a. "google-api-java-client").

Why you don't have to migrate

First the good news: gdata-java-client is not deprecated. We are keeping it in maintenance mode, fixing critical bugs, and adding a few minimal features. Why? Because we know how difficult the switching costs are for you. We know you've invested a great deal in this library. If this library is working for you, by all means keep using it.

There is also another important reason to keep using this library. It has been around much longer, and therefore is higher production quality. Here at Google, we are using this library in our production systems. You also have high confidence that this library won't change in backwards-incompatible ways. Since the google-api-java-client is still in alpha, these may be important considerations for you. The google-api-java-client library is also missing some features available in gdata-java-client such as resumable upload, though we are working to implement all of them eventually (if you find one that's important to you please make a feature request).

Why you will want to migrate

Technology moves fast, and if your needs have grown in scope, then you might need the newer client library. For example, if you want to access API's from Android, google-api-java-client supports Android but gdata-java-client does not. If you want to access JSON API's, again google-api-java-client supports JSON but gdata-java-client does not. In fact, gdata-java-client only supports Google Data API's built on the Atom XML specification, whereas google-api-java-client supports any XML or JSON format from any API (it even supports plugging in alternative formats). If you want to use partial XML response/update, google-api-java-client has a much better automated functionality to support partial than gdata-java-client. We are actively developing google-api-java-cient and it will benefit from all future developments. For example, we just added official Maven support to google-api-java-client. We have also started prototyping OAuth 2 in google-api-java-client. We don't plan to add these features to gdata-java-client.

But even if your needs haven't grown in terms of technologies, our API's will continue to grow. Part of the technological design of gdata-java-client is that we have to keep updating it as our API's add new XML elements or attributes. Unfortunately, this is a very time consuming and error-prone process, and our releases are too infrequent to keep up. google-api-java-client has a completely different model, in which there are classes representing the data format of our API responses. Although initially a one-time burden on you the developer, the upside is that you control these classes, and you don't depend on our slow and incomplete release process to provide you with them. If you are running into this barrier with the gdata-java-client, you may want to consider migrating to google-api-java-client.

What if I'm starting from scratch?

If you are writing a new client, and you are trying to choose between gdata-java-client or google-api-java-client, read the above paragraphs to help you decide. If you are willing to put up with some instability and have checked that google-api-java-client has all of the features you need (there are still a few missing features), you should consider starting with google-api-java-client. It will keep you "plugged-in" to the latest technologies and improvements.

Over time, we will add more samples and developer's guides to google-api-java-client to help you get started.

What if I have a large code base that uses gdata-java-client?

The good news here is that gdata-java-client and google-api-java-client are two completely different libraries with different package names. That means you can use both of them in your project without conflict. New code can use google-api-java-client and old code can continue to use gdata-java-client. This can provide a smooth migration path.

The bad news is that since the two client libraries are so different, switching existing working code from gdata-java-client to google-api-java-client is a non-trivial process.

First, you need to invest in writing a custom data model for the Google API. Please read the JavaDoc for the new XML data model in google-api-java-client. Over time, we will work on samples to demonstrate how to do this for Google API's. If there is already a sample for the API you are using, you are in luck. You may be able to copy the data model classes it uses into your application as a starting point. Of course those are just samples, and may only have the data classes and fields needed to meet the needs of that sample. If you are interested in seeing a sample for a particular Google API or feature of a Google API, please let us know so we can prioritize samples for features that most developers need.

But even if there is no sample, writing data classes is much easier with google-api-java-client than it was with gdata-java-client. Here is a complete working example for a YouTube video feed that we will use later:

public static class VideoFeed {
  @Key("entry") public List<VideoEntry> videos;
}

public static class VideoEntry {
  @Key public String title;
}

Second, there is a significantly different calling style betwen gdata-java-client and google-api-java-client. There is no YouTubeService in google-api-java-client. Instead, regardless of which API you are using, you start with the generic HttpTransport class. So whereas previously you might have written code like this:

  YouTubeService service = new YouTubeService(clientId);

You now have more lines of code with google-api-java-client:

    HttpTransport transport = GoogleTransport.create();
    GoogleHeaders headers = (GoogleHeaders) transport.defaultHeaders;
    headers.setApplicationName(clientId);
    headers.gdataVersion = "2";

Second, authentication is different between gdata-java-client and google-api-java-client. For example, if you are using ClientLogin, you are used to being able to do something like:

  service.setUserCredentials(username, password);

But now it's more lines of code:

    ClientLogin authenticator = new ClientLogin();
    authenticator.authTokenType = "youtube";
    authenticator.username = username;
    authenticator.password = password;
    authenticator.authenticate().setAuthorizationHeader(transport);

By the way, if you are already doing a migration of the client library, and you are still using ClientLogin and asking your end users to give your application their username and password, please strongly consider also migrating to OAuth.

Third, there is no YouTubeQuery to help you construct a URL. Instead, in google-api-java-client, you write your own YouTubeUrl class that extends GoogleUrl and adds custom YouTube query parameters. Here is an example:

public static class YouTubeUrl extends GoogleUrl {
  @Key public String orderby;
  @Key public String q;
  @Key public String safeSearch;
  public YouTubeUrl(String encodedUrl) {
    super(encodedUrl);
  }
}

To put it all together, whereas previously you might have written code like this:

public static void printPuppyVideos(YouTubeService service) {
  YouTubeQuery query = new YouTubeQuery(new URL("http://gdata.youtube.com/feeds/api/videos"));
  // order results by the number of views (most viewed first)
  query.setOrderBy(YouTubeQuery.OrderBy.VIEW_COUNT);

  // search for puppies and include restricted content in the search results
  query.setFullTextQuery("puppy");
  query.setSafeSearch(YouTubeQuery.SafeSearch.NONE);

  VideoFeed videoFeed = service.query(query, VideoFeed.class);
  for (VideoEntry videoEntry : videoFeed.getEntries()) {
    System.out.println("Title: " + videoEntry.getTitle().getPlainText());
  }
}

You might now write code like this:

public static void printPuppyVideos(HttpTransport transport) {
  YouTubeUrl url = new YouTubeUrl("http://gdata.youtube.com/feeds/api/videos");
  // order results by the number of views (most viewed first)
  url.orderBy = "viewCount";

  // search for puppies and include restricted content in the search results
  url.q = "puppy";
  url.safeSearch = "none";

  HttpRequest request = transport.buildGetRequest();
  request.url = url;
  VideoFeed videoFeed = request.execute().parseAs(VideoFeed.class);
  for (VideoEntry videoEntry : videoFeed.videos) {
    System.out.println("Title: " + videoEntry.title);
  }
}

There are other differences as well. For example, XML namespaces have to be specified manually. Also, inserting new items into a feed is done differently. Feel free to ask us questions to help you in your migration process, and over time we will update the document with more examples to help you. Good luck!

Comment by [email protected], Mar 21, 2011

Wow, this SUCKS! Every single code example above is longer and messier in the new library than the old one.

Comment by jeremyvillalobos, Mar 23, 2011

Can you show how to convert posts to create and edit documents ?

Comment by [email protected], Mar 31, 2011

dear sir, could you tell me this code will work without xml files or not.

Comment by [email protected], Apr 5, 2011

Finally sane verbosity using gdata-java-client. Thank you for great API, Yaniv Inbar!

Comment by [email protected], Apr 23, 2011

I'm a new fish, one question, where can I find your all service url? for example, what's the url that I can use it to get my books in google books service ?

Comment by [email protected], May 11, 2011

hello every one...i want to use gdata book search api in android...my code works well in java application...but same code i used in android..it raised an exception..may i use google-data-api client insted of gdata,.???

Comment by [email protected], Jul 10, 2011

active all

Comment by [email protected], Aug 26, 2011

I agree with sweetleonster, every example you showed, seems worse than the old API. Where is the object encapsulation ? Myself, as the client, would not like to set the header, api version, etc.

I'd simply like to do

YouTubeService? service = new YouTubeService?(clientId);

Why would I have to write my own classes for the entities like Video, VideoFeed?, etc? Why aren't they shipped with the api ?

is there an explanation to all this somewhere?

Thanks.

Comment by [email protected], Sep 3, 2011

This isn't nearly as bad as you make it out to be. Writing classes is a one time thing, and by doing that, they'll be specific to your needs. You can take advantage of partial requests which can decrease downloads from 53KB to 3 KB. When Google services update API's with new features etc, you're not left in the dust wondering why your gData doesn't do it yet. You can make it. Easily. Want a more powerful app? Use Google Api Client.

Comment by [email protected], Sep 12, 2011

Where are the samples/examples docs how how to migrate User provisioning code or even do it using the "google-api-java-client". In particular how do I do all of this: http://code.google.com/googleapps/domain/gdata_provisioning_api_v2.0_developers_protocol.html

With "google-api-java-client"??

Comment by [email protected], Oct 6, 2011

Include some samples for the following libraries, preferable with Oauth2

Google Analytics Data Export API Google Mail Migration API Google Apps Provisioning API Google Base Data API Google Calendar API Google Contacts API Google Documents List Data API Google Maps Data API Google Sites Data API

Comment by [email protected], Dec 21, 2011

I agree. I can't get oauth2 to work with the services. I can get both to work separately but without tracing the source code can't find examples or documentation for oauth2

Comment by [email protected], Jun 15, 2012

I'm using GData and I will stick with that. The new library is a lot messier and less idiot-proof!

Comment by [email protected], Aug 16, 2012

anyone find and answer to this?

Comment by [email protected] , Sep 12, 2011
Where are the samples/examples docs how how to migrate User provisioning code or even do it using the "google-api-java-client". In particular how do I do all of this: http://code.google.com /googleapps/domain/gdata_provisioning_api_v2.0_developers_protocol.html
With "google-api-java-client"??
Comment by [email protected], Sep 14, 2012

How does one request all youtube playlists for a user using v3 client API?

Youtube.Playlists.list takes playlist ID's but there is no method to get playlists by user ID.

Comment by [email protected], Feb 17, 2013

Does the jar lib given is an updated one? becoz evn trying the sample code given in the google manual,there are errors stating some methods are not found in the class path!!!

Comment by [email protected], Apr 3, 2013

While I think I understand the reasoning behind the complexity of these next-gen libraries (abstraction, extensibility, etc.), there are a number of serious problems with the implementation.

The primary issue is that an official API client should be designed to be as frictionless as possible to facilitate adoption and rapid development. This client does nothing to achieve that goal, and adoption will suffer as a result. My hope is that the complexity in the Java client is primarily due to it being a Java client and that the Ruby, Python, and other dynamic-language clients are much simpler.

That said, I really don't understand why there isn't something like to the following pseudocode:

class Google {

public Google(String id, String secret);
/ Bind this instance to an access token. / void authenticate(String code);

Userinfo getUserinfo();

}

Well designed, high-abstraction client objects take care of the vast majority of downstream developer use cases and facilitate broad adoption even among less technically sophisticated app developers.

Comment by [email protected], Sep 26, 2013

Any intelligent fool can make things bigger and more complex... It takes a touch of genius - and a lot of courage to move in the opposite direction. --Einstein


Sign in to add a comment
Powered by Google Project Hosting