Google App Engine Endpoints (REST services), with Java, Maven & Intellij (Part 1)

Sunday, May 19, 2013

App Engine endpoints allow you to create a RESTful service on Google’s infrastructure, which can be used as the backend for a mobile phone app, html site or some other client. Of course there are other similar and more standard solutions such as JAX-RS but I’m drawn to Google’s offering because I trust them to scale my service and, most importantly for me they have a built in authentication mechanism.

In this first post I’ll use Intellij and Maven on the iMac. In all honesty I think you would find the development process of the Google Eclipse plugin more polished - but I want to stick to standard development tooling i.e. Maven. The bottom line is I don’t want a plugin performing voodoo which I don’t understand, incase it breaks one day and leaves me clueless.

The easiest way to get started is to use the Google guestbook archetype. There is also a skeletal archetype (minus the guestbook), but that hasn’t been updated since 1.7.5. The guestbook project can be created via the Mac’s Terminal:

mvn archetype:generate \
-DgroupId=co.uk.planetjones \
-DartifactId=test-blood-pressure-monitor \
-Dversion=1.0-SNAPSHOT \
-DpackageName=co.uk.planetjones \
-DarchetypeGroupId=com.google.appengine.archetypes \
-DarchetypeArtifactId=guestbook-archetype \
-DarchetypeVersion=1.7.7 \
-DinteractiveMode=false

(anything which doesn't begin with -Darchetype should be changed to fit your own project)

Now load Intellij and select import project. Find the folder your maven archetype created, which is test-blood-pressure-monitor in this example. Select OK and keep clicking the dialogs until the JDK selection appears.

At the JDK selection, you should select a Java 1.7 SDK, as App Engine is moving to support only this Java version.

Your Intellij workbench should load. If you click "Maven Projects" you should see that 1.7.7 of the appengine-maven-plugin is available. We want to upgrade everything to version 1.8.0 though, so open the pom.xml and change to:

<appengine.target.version>1.8.0</appengine.target.version>

The archetype doesn't create the project with endpoint support, so you need to add in this dependency:

<dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-endpoints</artifactId>
    <version>${appengine.target.version}</version>
</dependency>

Finally change pom.xml to add the endpoint discovery stuff to the appengine-maven-plugin and modify the war plugin so your endpoints will be available when deploying (each time the WAR plugin executes the endpoints_get_discovery_doc goal will also be executed):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>2.3</version>
    <configuration>
       <webXml>${project.build.directory}/generated-sources/appengine-endpoints/WEB-INF/web.xml</webXml>
        <webResources>
        <resource>
        <directory>${basedir}/src/main/webapp/WEB-INF/</directory>
           <filtering>true</filtering>
              <targetPath>WEB-INF</targetPath>
                  <excludes>
                    <exclude>web.xml</exclude>
              </excludes>
           </resource>
       <resource>
                <directory>${project.build.directory}/generated-sources/appengine-endpoints</directory>
                <includes>
                    <include>WEB-INF/*.discovery</include>
                    <include>WEB-INF/*.api</include>
                </includes>
                <filtering>true</filtering>
            </resource>
        </webResources>
    </configuration>
</plugin>
<plugin>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-maven-plugin</artifactId>
    <version>${appengine.target.version}</version>
    <configuration>
        <enableJarClasses>false</enableJarClasses>
        <oauth2>false</oauth2>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>endpoints_get_discovery_doc</goal>
            </goals>
        </execution>
    </executions>
</plugin>

You usually need to update the Maven dependencies via: right-clicking your project > Maven > Remimport. All the App Engine dependencies should change to 1.8.0. Usually I find the App Engine Maven plugin fails to download. If this is the case you can add it as a dependency in your pom.xml to force it to download (then delete the dependency once it's in your local repository).

Eventually you should see a Maven toolbar which looks like:

At this point I usually delete all .java, .jsp and web.xml entries pertinent to the guestbook - this gives a nice empty project to play with.

Before we can do endpoint generation we need to define our Endpoint class. For now I'll just work on the API and hardcode their implementations. In a subsequent post I'll introduce datastore persistence. Let's create a simple entity class:

public class BloodPressureReading {
 
       private Integer id;
       private Date created;
       private Short systolic;
       private Short diastolic;
 
       public BloodPressureReading() {
       }
 
       // just for the example
       public BloodPressureReading (Integer id, Short systolic, Short diastolic) {
           this.id = id;
           this.created = new Date();
           this.systolic = systolic;
           this.diastolic = diastolic;
       }
 
       @Override
       public String toString() {
           return "BloodPressureReading{" +
                   "id=" + id +
                   ", created=" + created +
                   ", systolic=" + systolic +
                   ", diastolic=" + diastolic +
                   '}';
       }

And let's create the Endpoint class for this:

@Api(name="bp",
     version = "v1",
     description = "Test API for Blood Pressure Readings")
public class BloodPressureReadingEndpoint {
 
    private static List testData = new ArrayList<>();
    static {
        testData.add(new BloodPressureReading(1, (short)100, (short)200));
        testData.add(new BloodPressureReading(2, (short)80, (short)130));
        testData.add(new BloodPressureReading(3, (short)60, (short)100));
    }
    @ApiMethod(
            name = "bpreading.list",
            path = "bpreading",
            httpMethod = ApiMethod.HttpMethod.GET
    )
    public List list(@Nullable @Named("limit") Integer limit) {
        System.out.println("Limit was: " + limit);
        return testData;
    }
    @ApiMethod(
            name = "bpreading.get",
            path = "bpreading/{id}",
            httpMethod = ApiMethod.HttpMethod.GET
    )
    public BloodPressureReading get(@Named("id") Integer id) {
        System.out.println("ID is " + id);
        for(BloodPressureReading reading : testData) {
            if(reading.getId().equals(id)) {
                return reading;
            }
        }
        return null;
    }
    @ApiMethod(
            name = "bpreading.add",
            path = "bpreading",
            httpMethod = ApiMethod.HttpMethod.POST
    )
    public void add(BloodPressureReading reading) {
        System.out.println("Adding: " + reading);
    }
    @ApiMethod(
            name = "bpreading.delete",
            path = "bpreading/{id}",
            httpMethod = ApiMethod.HttpMethod.DELETE
    )
    public void delete(@Named("id") Long id) {
        System.out.println("Deleting: " + id);
    }
}

To test this locally execute:

appengine:endpoints_get_client_lib
appengine:devserver

Intellij's Maven support makes the execution of these goals simple:

After running the devserver goal, if you navigate to:

http://localhost:8080/_ah/api/discovery/v1/apis

via your browser you should see the service description:

{
  "kind" : "discovery#directoryList",
  "discoveryVersion" : "v1",
  "items" : [ {
    "kind" : "discovery#directoryItem",
    "id" : "bp:v1",
    "name" : "bp",
    "version" : "v1",
    "description" : "Test API for Blood Pressure Readings",
    "discoveryRestUrl" : "https://webapis-discovery.appspot.com/_ah/api/discovery/v1/apis/bp/v1/rest",
    "discoveryLink" : "./apis/bp/v1/rest",
    "icons" : {
      "x16" : "http://www.google.com/images/icons/product/search-16.gif",
      "x32" : "http://www.google.com/images/icons/product/search-32.gif"
    },
    "preferred" : true
  } ]
}

From the Terminal we can use curl to test the full service:

curl "http://localhost:8080/_ah/api/bp/v1/bpreading"
 
console displays: [INFO] Limit was: null
 
returns:
 
  "items" : [ {
    "id" : 1,
    "created" : "2013-05-19T10:40:47.919+02:00",
    "systolic" : 100,
    "diastolic" : 200
  }, {
    "id" : 2,
    "created" : "2013-05-19T10:40:47.919+02:00",
    "systolic" : 80,
    "diastolic" : 130
  }, {
    "id" : 3,
    "created" : "2013-05-19T10:40:47.919+02:00",
    "systolic" : 60,
    "diastolic" : 100
  } ]
}
 
----
 
curl "http://localhost:8080/_ah/api/bp/v1/bpreading?limit=2"
 
console displays: [INFO] Limit was: 2
 
----
 
curl "http://localhost:8080/_ah/api/bp/v1/bpreading/1"
 
returns:
 
{
  "id" : 1,
  "created" : "2013-05-18T18:45:41.061+02:00",
  "systolic" : 100,
  "diastolic" : 200
}
 
----
 
curl -i -X POST -H Accept:application/json -H Content-Type:application/json
-d '{"systolic" : 80, "diastolic" : 78}' 'http://localhost:8080/_ah/api/bp/v1/bpreading'
 
console displays:
[INFO] Adding: BloodPressureReading{id=null, created=null, systolic=80, diastolic=78}
 
----
 
curl -i -X DELETE -H Accept:application/json -H Content-Type:application/json
'http://localhost:8080/_ah/api/bp/v1/bpreading/2'
 
console displays: [INFO] Deleting: 2
 
----

If your responses are as expected then it's a success! If you ever get problems then it's a good idea to look into the:

target/generated-sources/appengine-endpoints

folder. This is where the Maven plugin puts its auto-generated files, so you can see the .api file which defines your endpoints.

After each change to the Endpoint class you must rerun appengine:endpoints_get_client_lib. Both the update and devserver goals will run the WAR plugin, so running endpoints_get:discovery_doc separately is not required.

Deploying to Google App Engine

This should be as simple as running appengine:update. However, I had an authentication problem which gave the error message:

Unable to update app: Error posting to URL:
https://appengine.google.com/api/appversion/create?app_id=planetjones-experiments&version=1&
404 Not Found
This application does not exist (app_id=u'planetjones-experiments').

By default Google uses OAuth 2 authentication when deploying. I just disabled this by adding the:

<oauth2>false</oauth2>

element to the configuration of the appengine-maven-plugin (see code line 48, earlier in this post). Doing this gives a prompt where you can enter your username and password for uploading to App Engine, when running the update goal.

In appengine-web.xml the application element must match the id of the application you created on appengine.google.com e.g. I changed mine to:

planetjones-experiments

When all this has changed you should just execute appengine:update and hopefully you get the magical:

BUILD SUCCESS

Testing on App Engine

You should be able to repeat all of the curl tests by substituting the localhost URL to your actual URL e.g.

https://planetjones-experiments.appspot.com/_ah/api/bp/v1/bpreading/1

Note the use of HTTPS.

In my case this gives:

{
 "id": 1,
"created": "2013-05-19T08:50:59.609Z",
  "systolic": 100,
  "diastolic": 200,
  "kind": "bp#bpreadingItem",
 "etag": "\"YF3eBGlNw_xRlLJpCVeJTVgJcSY/AX5SxpQiWTPtPBki3i0dp2DqjZA\""
 }

As Maven said:

SUCCESS

I have added this project to Github, so feel free to look around. Next I am going to secure this service, so only authenticated clients can access. And I will, of course, make the service interact with Google's datastore. But I feel it's beneficial in breaking this down into separate iterations, to aid understanding.

Feel free to tweet, mail or comment with any questions.