Google Cloud Endpoints short tutorial - part 1

Here a short tutorial on Google Cloud Endpoints (briefly presented in the previous post (http://googlielmo.blogspot.it/2013/04/google-cloud-endpoints.html)). For this tutorial I am referring to Eclipse Indigo and the Google Eclipse Plugin with the App Engine SDK 1.7.6. A little knowledge of the Google Plugin and the Google App Engine is required to better understand this tutorial.

Project creation

Open Eclipse and then create a new Web Application Project through the Google Plugin button. Select a name and the default package for the project and uncheck the GWT usage: we don't need a front end. The project name chosen for this tutorial is endpointtutorial.

Coding

Suppose you have this simple entity:


public class MyEntity {
public String entityName;
public String entityDescr;
}


and the business logic to access this kind of object:


public class MyBusinessClass {
public MyEntity getMyEntity() {
MyEntity myEntity = new MyEntity();
myEntity.entityName = "Test Entity";
myEntity.entityDescr = "Entity to test Endpoints";

return myEntity;
 }
}


Now let's go to write our first Endpoint:


public class MyEndpoint {

public String getEntity() {
MyBusinessClass myBusinessClass = new MyBusinessClass();
MyEntity myEntity = myBusinessClass.getMyEntity();

  return myEntity;
}
}


You can notice that it's a standard Java class. It's just a wrapper for your business logic (implemented using whatever Java library you want). To turn it on a real Endpoint you have just to annotate the class itself and its methods with the Annotations provided by the App Engine SDK:


import com.google.api.server.spi.config.Api;
import com.google.api.server.spi.config.ApiMethod;

@Api(name = "myendpoint",
description = "This retrieves an instance of MyEntity.")
public class MyEndpoint {

public MyEntity getEntity() {
MyBusinessClass myBusinessClass = new MyBusinessClass();
MyEntity myEntity = myBusinessClass.getMyEntity();

return myEntity;
  }
}


The name parameter for the @Api annotation is the name for the new API.
This annotation operation causes an automatic update of the web.xml file of the project. The Google plugin should have added to it the following rows for the Endpoint mapping:


<servlet-name>SystemServiceServlet</servlet-name>
  <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
  <init-param>
   <param-name>services</param-name>
   <param-value>org.blogspot.endpointtutorial.endpoint.MyEndpoint</param-value>
  </init-param>
 </servlet>
 <servlet-mapping>
  <servlet-name>SystemServiceServlet</servlet-name>
  <url-pattern>/_ah/spi/*</url-pattern>
 </servlet-mapping>

Local testing

Before proceeding you can test the new Endpoint on your local machine. Run (or debug) the project as Web Application, open a web browser and type the following URL:

http://localhost:8888/_ah/api/myendpoint/v1/myentity

Replace the local port if you use a different one than the default for the Google plugin Jetty instance. You should obtain a JSON output like this:

{
  "entityName" : "Test Entity",
  "entityDescr" : "Entity to test Endpoints"
}

The URL composition for the endpoint in this case is the following:

http://<hostname>:<port>/<endpoint_mapping>/<endpoint_name>/<endpoint_version>/<class_name_returned_in_lowercase>

Because it's possible to have more than one version of an endpoint, the plugin automatically sets the endpoint version to 1 (if not specified through the @Api annotation).
The endpoint of this example has just one method. But if you need to implement more than one method to be exposed you have only to annotate them through the @ApiMethod annotation:


@ApiMethod(httpMethod = "GET",
       name = "myentity.get", 
       path = "myentity/get")
public MyEntity getEntity() {
MyBusinessClass myBusinessClass = new MyBusinessClass();
MyEntity myEntity = myBusinessClass.getMyEntity();

return myEntity;
  }


You can also set the HTTP method, the name and the path for each single method.
Now to invoke locally this method by a web browser the URL changed this way:

http://localhost:8888/_ah/api/myendpoint/v1/myentity/get

Deploy to Google App Engine

If everything was fine, then you can proceed to deploy your application with the endpoints. First you have to create the application on your Google App Engine (GAE) space. Add the chosen name to the appengine-web.xml file of the project:

<application>endpointtutorial</application>

Check that the plugin already generated the descriptor for your APIs. You should find a file named myendpoint-v1.api into the war/WEB-INF folder of the project. Then right click on the project name and select Google -> Deploy to App Engine. The deploy process is the same as for all the applications to be deployed on GAE. If the deploy process went fine you could check the endpoint by a web browser:

https://endpointtutorial.appspot.com/_ah/api/myendpoint/v1/myentity/get

Don't forget to invoke it through HTTPS: otherwise you will obtain a 403 error.

Conclusions

To implement an Endpoint is a very simple process. Implement your business logic, implement a wrapper and then annotate it. The example shown in this tutorial is very simple, but I thought this is the best way to quickly understand this concept. I will try to go more in depth into other specific features (like security for example) in the future. In the second part of this tutorial (my next post) you will discover how the endpoints you have implemented can be easily and immediately ready to be consumed by an Android app. Stay tuned!