Simple Backend API with Maven

We recommend that you use the latest version of this feature, which is renamed to Cloud Endpoints Frameworks for App Engine. This new version supports App Engine standard environment, provides lower latency, and has better integration with App Engine. For more details, see Migrating to 2.0.

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.


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.


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. Create or select a Cloud Platform project in the Cloud Platform Console and then ensure that an App Engine application exists and billing is enabled:

    Go to App Engine

    The Dashboard opens if an App Engine application already exists in your project and billing is enabled. Otherwise, follow the prompts for choosing a region and enabling billing.

Cloning the tutorial project

Clone the HelloWorld sample from GitHub:

git clone

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 and 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 file used for application logging. Used to set the default log level (Error, Warning, Info, etc.)
web.xml Does all the mappings required for the backend API servlet. Used for clients and authorization. For this simple sample, we won't modify this. The JavaBean used to send data through the endpoints. 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] ------------------------------------------------------------------------
    [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,

    For example, on Mac OS X,

    /Applications/Google\\ Chrome --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost: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 startup
    [INFO] INFO: The admin console is running at http://localhost:8080/_ah/admin
    [INFO] April 13, 2016 9:44:47 AM doStart
    [INFO] INFO: Dev App Server is now running
  4. Visit the APIs Explorer at this URL:


    (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. walkthrough

The following code shows the contents of the file

/** 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. walkthrough

The following code shows some of the contents of the file

/** An endpoint class we are exposing */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "",
        ownerName = "",
        packagePath = ""),
    clientIds = {Constants.WEB_CLIENT_ID, Constants.ANDROID_CLIENT_ID, Constants.IOS_CLIENT_ID},
    audiences = {Constants.ANDROID_AUDIENCE})
/** 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.


To avoid incurring charges to your Google Cloud Platform account for the resources used in this tutorial:

  1. Go to the Cloud Platform Console.
  2. In the list of projects, select the project that you want to shut down.
  3. In the prompt, type your project ID to confirm the deletion.
  4. Click Shut down to schedule your project for deletion.

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...

Cloud Endpoints