MigratingToGoogleApiJavaClient
Migrating to Google API Client for Java
Updated informationWe 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 informationWARNING: 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 migrateFirst 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 migrateTechnology 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! |
Wow, this SUCKS! Every single code example above is longer and messier in the new library than the old one.
Can you show how to convert posts to create and edit documents ?
dear sir, could you tell me this code will work without xml files or not.
Finally sane verbosity using gdata-java-client. Thank you for great API, Yaniv Inbar!
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 ?
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,.???
active all
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.
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.
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"??
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
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
http://developer.android.com/reference/android/view/accessibility/AccessibilityManager.html
I'm using GData and I will stick with that. The new library is a lot messier and less idiot-proof!
anyone find and answer to this?
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.
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!!!
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 {
}
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.
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