Getting Started with Endpoints Frameworks on App Engine

This page shows you how to configure, deploy, and send requests to a sample API running on Google App Engine standard using the Google Cloud Endpoints Frameworks for App Engine in Java 8 and Maven 3.3.9. Cloud Endpoints Frameworks consists of tools, libraries and capabilities that allow you to generate APIs and client libraries from an App Engine application.

Task list

Use the following high-level task list as you work through the tutorial. All tasks are required to successfully send requests to the API.

  1. Set up a Cloud Platform project. See Before you begin.
  2. Install required software and create an App Engine app. See Installing and configuring required software.
  3. Download the sample code. See Getting the sample code.
  4. Generate an OpenAPI configuration file. See Configuring Endpoints.
  5. Deploy the Endpoints configuration to create a Cloud Endpoints service. See Deploying the Endpoints configuration.
  6. Optionally, run the sample on your computer. See Running the sample locally
  7. Create a backend to serve the API and deploy the API. See Deploying the API backend.
  8. Send a request to the API. See Sending a request to the API.
  9. Track API activity. See Tracking API activity.
  10. Avoid incurring charges to your Google Cloud Platform account. See Clean up.

Before you begin

  1. Sign in to your Google Account.

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

  2. Select or create a GCP project.

    Go to the Manage resources page

  3. Make sure that billing is enabled for your project.

    Learn how to enable billing

  4. Note the project ID, because you'll need it later.

Installing and configuring required software

  1. If you don't have Java 8 installed, download the Java Development Kit (JDK) from Oracle's download site and install it.
  2. If you don't have Maven 3.3.9 or higher, download and install it.
  3. Note for Windows users: If you are installing the JDK and Maven on Windows, install them in a directory that does not have a space in the path. See Maven on Windows for more information.

  4. You will need an application to send requests to the sample API.

    • Linux and Mac users: This tutorial provides an example using curl, which typically comes pre-installed on your operating system. If you don't have curl, you can download it from the curl Releases and Downloads page.
    • Windows users: This tutorial provides an example using Invoke-WebRequest, which is supported in PowerShell 3.0 and later.
  5. Download and initialize the Cloud SDK.
  6. Run the following commands:
    1. Make sure that Cloud SDK is authorized to access your data and services on Google Cloud Platform:
      gcloud auth login
    2. Use Application Default Credentials:
      gcloud auth application-default login
    3. Install the Cloud SDK app-engine-java component:
      gcloud components install app-engine-java
    4. Update to the latest version of Cloud SDK and all components:
      gcloud components update
  7. Create an App Engine app:
    1. Set the default project to your project ID.
      gcloud config set project [YOUR_PROJECT_ID]

      Replace [YOUR_PROJECT_ID] with your Cloud project ID. If you have other Cloud Platform projects, and you want to use gcloud to manage them, see Managing Cloud SDK Configurations.

    2. Select the region where you want to create your App Engine app. Run the following command to get a list of regions:
      gcloud app regions list
    3. Create an App Engine app using the following command. Replace [YOUR_PROJECT_ID] with your Cloud project ID and [YOUR_REGION] with the region that you want the App Engine app created in.
      gcloud app create \
      --project=[YOUR_PROJECT_ID] \

Getting the sample code

To clone the sample API from GitHub:

  1. Clone the sample repository to your local machine:

    git clone
  2. Change to the directory containing the sample code:

    cd java-docs-samples/appengine-java8/endpoints-v2-backend

Configuring Endpoints

The sample includes the Endpoints Frameworks tool that generates an OpenAPI configuration file that describes the sample code's REST API. Follow the steps in this section to configure and build the sample Maven project so that you can then generate the OpenAPI configuration file.

Adding the project ID to the sample API code

You must add the project ID obtained when you created your Cloud project to the sample's pom.xml before you can deploy the code.

To add the project ID:

  1. Edit the file java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml.

  2. Search for <>, and replace the value YOUR_PROJECT_ID with your Cloud project ID.

    For example:

  3. Save your changes.

Building the sample project

To build the project:

  1. Make sure you are in the directory java-docs-samples/appengine-java8/endpoints-v2-backend.

  2. Invoke the command:

    mvn clean package
  3. 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

Generating the OpenAPI configuration file

You use a tool from the Frameworks library to generate an OpenAPI configuration file called openapi.json. This file describes the sample code's REST API.

To generate the OpenAPI configuration file:

  1. Invoke the Endpoints Frameworks tool using this command:

    mvn endpoints-framework:openApiDocs
  2. Wait for the configuration spec to build. When it finishes you'll see a message similar to this one:

    OpenAPI document written to target/openapi-docs/openapi.json

    Ignore any messages about failure to load a static logger class.

Deploying the Endpoints configuration

To deploy the Endpoints configuration, you use Service Infrastructure, Google’s foundational services platform, used by Endpoints Frameworks and other services to create and manage APIs and services

To deploy the configuration file:

  1. Make sure you are in the directory java-docs-samples/appengine-java8/endpoints-v2-backend.

  2. Deploy the OpenAPI configuration file that was generated in the previous section by invoking the following command:

    gcloud endpoints services deploy target/openapi-docs/openapi.json

This creates a new Cloud Endpoints service with the name in the format This name is configured in pom.xml and other configuration files included in the sample. Note that when you deploy the API on App Engine, a DNS record is created using the name format, which is the fully qualified domain name (FQDN) that you use when you send requests to the API.

As it is creating and configuring the service, Service Management outputs a great deal of information to the terminal. You can safely ignore the warnings about the paths in openapi.json not requiring an API key. On successful completion, you will see a line like the following that displays the service configuration ID and the service name:

Service Configuration [2017-02-13-r2] uploaded for service []

In the above example, 2017-02-13-r2 is the service configuration ID and is the service name.

See gcloud endpoints services deploy in the Cloud SDK Reference documentation for more information.

Running the sample locally

After deploying the Endpoints configuration, you can run the sample locally.

  1. Set the ENDPOINTS_SERVICE_NAME environment variable to: [YOUR_PROJECT_ID]

    In Linux or Mac OS:


    In Windows PowerShell:


    Replace [YOUR_PROJECT_ID] with your Cloud project ID.

  2. Acquire new user credentials to use for Application Default Credentials.

    gcloud auth application-default login
  3. Run the development server:

    mvn appengine:run
  4. Send a request to the local instance

    The local instance is reachable on http://localhost:8080 as indicated by the logs printed by the mvn appengine:run command:

    [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/

    To query the local instance:

    curl \
        --header "Content-Type: application/json" \
        --request POST \
        --data '{"message":"hello world"}' \

    If you are on Windows, instead invoke the following PowerShell cmdlet:

    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
        -Headers @{"content-type"="application/json"} -URI `

    You should get a 200 response with the following data:

     "message": "hello world"

Deploying the API backend

So far you have deployed the OpenAPI configuration to Service Management, but you have not yet deployed the code that will serve the API backend. This section walks you through deploying the sample API to App Engine.

To deploy the API backend:

  1. Make sure you are in the directory java-docs-samples/appengine-java8/endpoints-v2-backend

  2. Deploy the API implementation code using Maven:

     mvn appengine:deploy

    The first time you upload a sample app, you may be prompted to authorize the deployment. Follow the prompts: when you are presented with a browser window containing a code, copy it to the terminal window.

  3. Wait for the upload to finish.

    We recommend that you wait a few minutes before sending requests to your API while App Engine completely initializes.

Sending a request to the API

After you deploy the API and its configuration file, you can send requests to the API.

To send a request to the API:

  1. From a command line, invoke the following curl command:

     curl \
         --header "Content-Type: application/json" \
         --request POST \
         --data '{"message":"hello world"}' \

    If you are on Windows, instead invoke the following PowerShell cmdlet:

     (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
         -Headers @{"content-type"="application/json"} -URI `

    Replace [YOUR_PROJECT_ID] with your Cloud project ID.

    You should get a 200 response with the following data:

     "message": "hello world"

If you did not get a successful response, see Troubleshooting Response Errors.

Tracking API activity

  1. View the activity graphs for your API in the Endpoints page.
    View Endpoints activity graphs
    It may take a few moments for the request to be reflected in the graphs.
  2. Look at the request logs for your API in the Logs Viewer page.
    View Endpoints request logs

Clean up

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

  1. Go to the GCP Console to shut down your GCP project:

    Go to the Projects page

  2. Select the GCP project that you used to run this Cloud Endpoints quickstart and then click Delete.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine
Need help? Visit our support page.