Simple Backend API with Maven

This code walkthrough shows a pre-built Maven project containing a simple Cloud Endpoints backend API that you can run and test locally without having to build a client. The purpose is to show the basic structure and behavior of a backend API.

Objectives

In this tutorial, you'll learn how to:

  • Set up your development environment for Cloud Endpoints.
  • Run and test a simple backend API.
  • Learn the basics of backend API construction.

Costs

App Engine has free a level of usage. If your total usage of App Engine is less than the limits specified in the App Engine free quota, there is no charge for doing this tutorial.

Before you begin

  1. Install the Java 7 SDK and set up your environment as described in Configuring Java.
  2. Install Maven 3.1 or greater as described in Installing Maven 3.1+.
  3. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  4. Select or create a Cloud Platform Console project.

    Go to the Projects page

  5. Enable billing for your project.

    Enable billing

Cloning the tutorial project

Clone the HelloWorld sample from GitHub:

git clone https://github.com/GoogleCloudPlatform/appengine-endpoints-helloworld-java-maven

Alternatively, you can download the sample as a zip file and extract it.

Viewing the project layout and files

If you execute a tree command or equivalent on the directory appengine-endpoints-helloworld-java-maven, this is what the structure of the project looks like:

Maven Project Layout

We'll cover the contents of MyBean.java and YourFirstAPI.java in detail during the tutorial. To give you a quick synopsis of these files for now, here's a brief inventory:

File Description
pom.xml Project settings and dependencies used by Maven.
appengine-web.xml Used to specify the project ID this application is deployed to, the application version, and the location of the logging.properties file used for application logging.
logging.properties Used to set the default log level (Error, Warning, Info, etc.)
web.xml Does all the mappings required for the backend API servlet.
Constants.java Used for clients and authorization. For this simple sample, we won't modify this.
MyBean.java The JavaBean used to send data through the endpoints.
YourFirstAPI.java Contains the backend API definition and functionality.

Building and running locally

  1. In the root directory of the project, appengine-endpoints-helloworld-java-maven/ build the project by invoking the command

    mvn clean install
    

    Wait for the project to build. When the project successfully finishes, you will see a message similar to this one:

    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 14.846s
    [INFO] Finished at: Wed April 13 09:43:09 PDT 2016
    [INFO] Final Memory: 24M/331M
    
  2. In a terminal window, start a new Chrome session as follows:

    <Full-Path-to-Chrome> --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:8080,http://0.0.0.0:8080
    

    For example, on Mac OS X,

    /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:8080,http://0.0.0.0:8080
    
  3. Start the API in the development server by invoking the command

    mvn appengine:devserver
    

    Wait for the dev server to start up. When the server is ready, you will see a message similar to this one:

    [INFO] INFO: Module instance default is running at http://localhost:8080/
    [INFO] April 13, 2016 9:44:47 AM com.google.appengine.tools.development.AbstractModule startup
    [INFO] INFO: The admin console is running at http://localhost:8080/_ah/admin
    [INFO] April 13, 2016 9:44:47 AM com.google.appengine.tools.development.DevAppServerImpl doStart
    [INFO] INFO: Dev App Server is now running
    
  4. Visit the APIs Explorer at this URL:

    http://localhost:8080/_ah/api/explorer
    

    (The Google APIs Explorer is a built-in tool that lets you send requests to a backend service without using a client app.)

  5. Click myApi API V1 to display the methods available from this API.

  6. Click myApi.sayHi to display the Explorer for this method:

    SayHi form

  7. Supply any name you want in the name field, then click Execute without OAuth

  8. When finished, stop the browser you started with the command line above, because you should not use it for normal browsing for safety reasons.

Configuration files

In this simple tutorial, we won't cover the configuration files, such as pom.xml, appengine-web.xml, and web.xml. These are covered in more detail in the more advanced Backend API with Maven sample.

MyBean.java walkthrough

The following code shows the contents of the file MyBean.java:

/** The object model for the data we are sending through endpoints */
public class MyBean {

  private String myData;

  public String getData() {
    return myData;
  }

  public void setData(String data) {
    myData = data;
  }
}

This class is used to return data from the backend API to the caller. Note that you need to use a JavaBean object to send data through the backend API.

YourFirstAPI.java walkthrough

The following code shows some of the contents of the file YourFirstAPI.java:

/** An endpoint class we are exposing */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))
...
/** A simple endpoint method that takes a name and says Hi back */
@ApiMethod(name = "sayHi")
public MyBean sayHi(@Named("name") String name) {
  MyBean response = new MyBean();
  response.setData("Hi, " + name);

  return response;
}

Notice the annotation @Api; this is where you set the configuration of the backend API, such as its name and version, along with other possible settings. (See Endpoint Annotations for all of the available attributes of this annotation.)

This is where you specify the name and version of the API, both of which show up in the API Explorer

Notice the @ApiMethod annotation; it allows you to configure your methods at a finer level than the API-wide configuration.

Finally, notice the use of the javax.inject.Named annotation (@Named) in the sayHi method definition. You must supply this annotation for all parameters passed to server-side methods, unless the parameter is an entity type.

What's next

This tutorial walked you through the process of building a simplistic backend API. For a more complete example of building a backend API, including GET/POST methods and OAuth authentication, see Backend API with Maven.

Send feedback about...