Google Cloud Endpoints Tutorial – Part 3

Welcome to Part 3 of the Google Cloud Endpoints Tutorial.

The series so for:

  • Part 1 : We looked at writing a Google Cloud Endpoints class manually by using the various annotations and Exception classes that are available. We create a Quotes API that provided a JSON + REST based interface to manage Quotes (add, modify, delete and retrieve quotes).
  • Part 2 : We generated the Google Cloud Endpoints class from a JDO Annotated Entity class by using the Code Generation tools provided in the library.
  • Part 3 : Generated the Cloud Endpoints Client Library for Android and wrote an Android application that invokes the Endpoints API.
  • Part 4: We wrote a JavaScript client for our Endpoints API.

In this episode

We have looked at generating the API implementation so far. You can pick and choose, whether you want to write it by hand or use the generated classes and tweak them to your liking. Whichever way you go, what we have now with us is an API backend that is hosted on the Google Cloud (App Engine) and we need to start consuming it via client applications.

In this part of the tutorial, we are going to look at writing an Android client that consumes the Quotes API that we have ready and hosted. The tutorial will look at writing the application from scratch and demonstrating the List Quotes and Add New Quote function. Once you see that work, you can extend the Android application a bit further by incorporating the Edit Quote and Delete Quote as needed.

What do you need ?

  • Basic understanding of Android Application Development. Specifically, we will be looking at writing a few Activity classes, starting one Activity from another (via the Intent), using the Android AsyncTask to asynchronously invoke our API backend from the Android client. We shall be using Android stuff like ListActivity, Alert, Toast, Layouts, etc. If you are looking at brushing up on your Android fundamentals, look no further than this.
  • You have a working development environment for Google App Engine. This includes the Google Eclipse plugin.
  • You have a working development environment for Android. I have used Eclipse with the ADT Plug-in.

My Development Environment

This remains the same, no changes at all. My development environment is given below:

  • Eclipse Juno
  • Google Eclipse plugin with App Engine SDK 1.8.8
  • Android ADT Plugin with latest Android SDK installed.
  • Mac + Windows machine (I kept switching from one to another, to keep everyone happy ;-))

Attention-> Cloud Endpoints became GA (General Availability) in Release 1.8.7 of the App Engine SDK. The latest release as of App Engine at the time of writing is 1.8.9.

Revisiting the Quotes API

Let us recap quickly on what we have done so far. We have written a Quotes API hosted on Google App Engine that allows us to perform CRUD operations via a HTTP REST API. A Quote record contains a couple of attributes, the author and the famous quote that the author gave.

If you look at the API Methods, we had the following methods exposed:

Screen Shot 2014-01-12 at 4.21.42 PM

Additionally, we have the application live and available on App Engine. And we have some records added to it, so that in case we do a listQuote, a record or two is available.

In case you are planning to follow the rest of the article, it would help to have the Quotes API ready and available under your App Engine application id.

Generate Google Cloud Endpoints library

Google Cloud Endpoints provides a way for us to generate the client side libraries. This can be done via the command line but we will be using the Eclipse plugin to keep things the way it has been so far.

Assuming that you already have your Eclipse Project for Quotes API Project loaded in Eclipse, simply right click on the Project, go to Google and then Generate Cloud Endpoint Client Library as shown below:

Screen Shot 2014-01-12 at 11.38.43 AM

This will start generating Java classes that constitute the Client Library. It takes a while as shown by the dialog below:

Screen Shot 2014-01-12 at 11.37.58 AM

Once done, you can take a look at the various folders that have been generated for you. The folders include the sources that act as a stub for your Quotes API and also a set of dependent JAR files.

For the Quotes API project that I have, the Client library folders are shown below:

eclipse3

At the same level as your src folder, you will find the endpoint-libs folder in which the sources and JARs are present. 

The main points to take away is that:

  • You will need to take the classes that are generated in the quoteendpoint-v1-generated-source folder. These classes are client classes that act as a stub and which you can use in your Android application to invoke the CRUD operations in your hosted API.
  • More importantly, thats not all. You will need a bunch of dependent JAR files that are present in the dependencies folder and which you will need to carry along and link to in your Android project for everything to compile and eventually work.

We shall see that in a while.

Android Application Development

Before we dive into development of the Android client application, let us see it in action to better understand what we shall be building here.

When you launch the application, the first screen (Activity) is shown below:

androidapp1

The UI is simple and please do forgive me for my design skills :-) It has 3 buttons:

  • List Quotes : When clicked, it will start a new Activity that will Retrieve the current list of Quotes from the live App Engine application. A sample screen is shown below:androidapp2The List Activity is a simple ListActivity in Android. We use an Async Task to make the call via the Client library to get the Quotes and display them.
  • Add Quote : This Activity presents a simple form to the user to provide the Author name and the quote (message) as shown below:

androidapp3

When you click on Add, we will make a call to the Client library, which in turn will invoke the POST method to insertQuote in the live App. On successful addition, a message is shown to the user and when you go back to the List Quotes Activity, you see the newly added quote too, as given below:

androidapp5

Side Note: This is my only chance of being listed next to 2 great individuals. I stand no other chance. :-)

The 3rd button (About Appsimply shows a simple Alert box and displays the name and the version number.

Let’s get started with the Android Application Development now. All the steps now will happen inside the Android Development Environment. I am using the ADT plugin inside of Eclipse. If you are using Android Studio, steps should be more or less familiar.

Generate Skeleton App

The first step is to create a new Project. Simply go to File -> New -> Android Application Project

Screen Shot 2014-01-12 at 7.22.59 PM

Click on Next. In the screen below, we provide the name our App (FamousQuotesAndroid) along with package name. I have API 18 but you could have some other one too. 

Screen Shot 2014-01-12 at 7.23.43 PM

Click on Next. Deselect the Create custom launcher icon. Let the other values be as is and click on Next.

Screen Shot 2014-01-12 at 7.24.01 PM

Go with the default on this screen too as shown below and click on Next.

Screen Shot 2014-01-12 at 7.24.14 PM

The final screen is shown below. Simply click on Finish. 

Screen Shot 2014-01-12 at 7.24.34 PM

This will generate the Android Project. Ensure that it all compiles fine and verify that you are able to launch a AVD and run the basic application.

Add Google Client Library Classes and Dependencies (JARs)

The next step that we need to do is to add all the Cloud Endpoint classes and the Dependent JARs that were generated in the Quotes API Project.

You will need to add the JAR files shown below to the libs folder of your Android project. These JARs will be available in the dependencies folder of your Cloud Endpoint generated folder that we saw earlier.

The JAR files that you need to add are shown below:

eclipse1

The next thing to do is to add the Cloud Endpoint Java Source files that were generated in the quoteendpoint-v1-generated-source folder. Shown below is my Android Project Source structure:

eclipse4

As pointed out above, we have simply put the Cloud Endpoints generated Java files in the com.mindstorm package.

Similarly, the folder that you see below that i.e. Android Activities code is all the Android code that we shall see in a moment. It contains the Activity classes that compromise our Android application.

Understand Google Client Code and calling mechanism

It is important to understand to some extent what the Google Cloud Endpoints client classes look like.

  • The main class that you will deal with is the Quoteenpoint.java file. This is your starting point.
  • It contains the DEFAULT_ROOT_URL and the DEFAULT_SERVICE_PATH that you should modify if necessary so that the application points to your App Engine API which is hosted live at your application id.
  • It contains an inner class named Builder that you need to construct and get an instance of. The Builder constructor takes 3 parameters : Instance of the HTTP Connection Transport, an instance of GSONFactory for helping out in Java-JSON translations and an initializer.
  • Once the instance of a Builder is created, you will find that you can invoke all the API methods like listQuote, inserQuote, remoteQuote, getQuote and updateQuote, which you can then execute(). We shall see this in a while.

Android Activity Classes

Now let us go through the Android code. You do need to know a bit of basic Android Development over here, so most of the things should be straightforward. I have kept them deliberately simply and at a high level, you need to know the following things in Android:

  • Writing a basic Activity class and adding the entries in the AndroidManifest.xml file.
  • Invoking i.e. starting one Activity from the other. Basic Intent is used here.
  • Writing Event Handlers for button clicks. Knowledge of Linear Layout.
  • ListActivity
  • AsyncTask and why it is needed.

Android Main Activity class

This is the first screen that is shown in the Android application. There are 3 event handlers i.e. OnClick Listeners for the 3 buttons i.e. List Quotes, Add Quote and About App.

The List Quotes and Add Quote button click handlers simply start the respective Activities i.e. AddQuoteActivity and QuotesListActivity, that we shall see next.

Add Quote Activity

The code is given below but let us look at the main points:

  • The user enters the values for Author Name and Message and clicks on Add button.
  • The Add button click handler does some check for values and then invokes an Async Task: AddQuoteAsyncTask and passes the Strings i.e. Author Name and Message to it.
  • Pay attention to the AddQuoteAsyncTask class and the doInBackground method. Over here we construct the Quoteendpoint.Builder, create the Quote object and execute the insertQuote object. As simple as that.
Quoteendpoint.Builder builder = new Quoteendpoint.Builder(AndroidHttp.newCompatibleTransport(), new GsonFactory(), null);
Quoteendpoint service = builder.build();
Quote quote = new Quote();
quote.setAuthor(params[0]);
quote.setMessage(params[1]);
response = service.insertQuote(quote).execute();
  • In the postExecute method of the Async Task, we simply clear up the fields.

Quotes List Activity

This code should be straight forward now.

  • In the onCreate we invoke the QuotesListAsyncTask.
  • The QuotesListAsyncTask will create the builder, invoke the listQuote method and collect the responses into a collection.
  • Finally in the postExecute method, we add the data to the List Adapter and boom, it displays the stuff in the ListView Control.

This post talks about the list Quotes and Add Quote methods and has demonstrated that in the Android application. I hope that it is demonstrative of the fact that the update Quote, delete Quote and get Quote can also be executed accordingly and you can try it out.

Response Times

One of the important points to consider while using Google Cloud Endpoints is that your API is hosted on the App Engine platform. It is known that your application instance is not always running when for you. If it is idle for a while, your Application instance is removed and then on the next request, the instance is started up. The starting up (cold start) usually takes a while and anyone who has done work with App Engine is aware about this.

For e.g. look at the App Engine console log for the incoming requests below. I have highlighted in red, the abnormally high request processing time for particular API calls. 

logconsole1

This is not to alarm you but it is something that you should be aware of. Definitely an API request that takes 15+ seconds to complete is not what you want. But at the same time, if the instance is alive, you do see a fast response time.

Please note that Google App Engine addresses the issue of keeping the instance alive via Warmup requests. Please read up on that.

Full Project Download

You can download both the Projects from GitHub.

Hope you liked this episode of Google Cloud Endpoints in which we generated the Client Libraries for Android and also consumed it from an Android application.

Stay tuned for more episodes. Till the next one

About these ads

About rominirani

Google Developer Expert Cloud 2014. Harnessing the power of software by learning, teaching and developing simple solutions. I love learning about new technologies and teaching it to others.
This entry was posted in Cloud Computing, Google App Engine and tagged , , . Bookmark the permalink.

24 Responses to Google Cloud Endpoints Tutorial – Part 3

  1. Pingback: Google Cloud Endpoints Tutorial – Part 1 | iRomin

  2. Pingback: Google Cloud Endpoints Tutorial – Part 2 | iRomin

  3. Pingback: Google Cloud Endpoints Tutorial – Part 4 | iRomin

  4. ayman Ibaida says:

    Hi I am tryin to use your sample .. the endpoint working properly. the android addquote working properly but the listquote is not working i keep receiving this
    02-10 05:06:48.663: D/Could not retrieve Quotes(1288): java.lang.SecurityException: Permission denied (missing INTERNET permission?)

  5. Pingback: Google Cloud Endpoints Tutorial – Part 5 | iRomin

  6. Pingback: Google Cloud Endpoints Tutorial – Part 6 | iRomin

  7. Pingback: Google Cloud Endpoints Tutorial – Part 7 | iRomin

  8. unkdrew says:

    Hi rominirani, it is really a great tutorial, but right now when I try to run my android app, the logcat says there is a 500 Internal Server Error, and it is an Unknown Error which gives me no clue of how to solve it. Do you have any idea about this? Thx!

  9. unkdrew says:

    Sorry, I did not change the config of the URL, now it’s working. But I also want to know how I can integrate GCM into this Cloud Endpoint project? Thanks.

    • rominirani says:

      Here are my thoughts on the same:

      1. If you are using Endpoints , then the idea is that you are regularly invoking / polling the API Endpoint in case you need to get data.
      2. If the above is inefficient due to which you are planning to use push notifications, then I believe you should look at the Mobile Backend Start project that provides a quick Backend project to deploy on App Engine along with Push Notification integration. Take a look at : https://developers.google.com/cloud/samples/mbs/

  10. Sharan says:

    hi
    Thanks for your tuto.
    But i am getting following error.
    “Conversion to Dalvik format failed with error 1″
    can you help me in this.

  11. Nagar says:

    I’m facing error when I generate client libraries. Any suggestion for me? I’m following your great tutorial.

    • rominirani says:

      What is the error that you are getting ? Are you trying to generate from command line or from Eclipse. Please give this information, so that I can try to help.

  12. Hello rominirani, first of all great tutorial!!

    I’m having troubles with the part:
    Quoteendpoint.Builder builder = new Quoteendpoint.Builder(AndroidHttp.newCompatibleTransport(), new GsonFactory(), null);

    I’m using Android Studio and I keep getting the error that can not resolve to AndroidHttp.

    The only option I have is AndroidHttpClient.

    Any ideas on what it can be?

    Marcus

    • rominirani says:

      This is likely to happen if you have not linked the JAR files that are needed in the project. When you generate the Endpoint client library, there is also a dependencies folder that contains several JAR files and chief among them being the google-api-client-*.jar files. Please make sure that those JAR files are present and the class should get resolved.

  13. Albert says:

    Hi Romin!

    your tutorial is awesome, thanks for it.
    I have a question, I imported your projects into Eclipse to testing.
    I change the “DEFAULT_ROOT_URL” in QuoteendPoint (Android project).
    I can see a field “USERINFO_EMAIL” in QuoteendpointScopes (Android project) but i don’t change it.
    My LogCat show this:
    401 Unauthorized
    {
    “code”: 401
    “errors”: [
    {
    "domain": "global",
    "location": "Authorization",
    "locationType": "header"
    "message": "User is Not Valid"
    "reason": "required"
    }
    ],
    “message”: “User is Not Valid”
    }

    How can i do to resolve this error?

    Thanks!

  14. Chris says:

    Hi Rominirani,

    Thanks for the tutorial, very useful.

    Is there a method to find a specific quote, essentially querying for a specific quote instead of retrieving and listing all quotes.

    Chris

    • rominirani says:

      Hi Chris,

      Thanks for the feedback. Yes – there is a getQuote method that requires you to pass in a long i.e. Quote Id. It should return you the particular Quote record.

      Does that work for you ?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s