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 and install required software. See Before you begin.
  2. Download the sample code. See Getting the sample code.
  3. Generate an OpenAPI configuration file. See Configuring Endpoints.
  4. Deploy the Endpoints configuration to create a Cloud Endpoints service. See Deploying the Endpoints configuration.
  5. Optionally, run the sample on your computer. See Running the sample locally
  6. Create a backend to serve the API and deploy the API. See Deploying the API backend.
  7. Send a request to the API. See Sending a request to the API.
  8. Track API activity. See Tracking API activity.
  9. Avoid incurring charges to your Google Cloud Platform account. See Clean up.

Before you begin

  1. Create or select a Cloud Platform project in the Cloud Platform Console and then ensure that project includes an App Engine application:
    Go to App Engine

    The Dashboard opens if an App Engine application already exists in your project. Otherwise, you are prompted to choose the region where you want your App Engine application located.

    Note: This application should be run in a B4_1G instance class for improved performance.

  2. Note the ID of the project, because you'll need it later.
  3. Install curl for testing purposes. This may have already been provided by your OS. If you are on Windows, you can use PowerShell 5 or newer instead.
  4. Download the Google Cloud SDK.
  5. Update the Cloud SDK and install the Endpoints components:
    gcloud components update
  6. Make sure that Cloud SDK (gcloud) is authorized to access your data and services on Google Cloud Platform:
    gcloud auth login
    A new browser tab opens and you are prompted to choose an account.
  7. Set the default project to your project ID:
    gcloud config set project [YOUR_PROJECT_ID]

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

  8. If you don't have Java 8 installed, download the Java Development Kit (JDK) from Oracle's download site and install it.

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

  9. If you don't have Maven 3.3.9 or higher, download and install it.

Getting the sample code

To clone the sample API from GitHub:

  1. Clone the sample repository to your local machine:

     git clone https://github.com/GoogleCloudPlatform/java-docs-samples
    
  2. Change to the directory containing the sample code:

     cd java-docs-samples/appengine/endpoints-frameworks-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/endpoints-frameworks-v2/backend/pom.xml.

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

    For example:

    <endpoints.project.id>example-project</endpoints.project.id>
    
  3. Save your changes.

Building the sample project

To build the project:

  1. Make sure you are in the directory java-docs-samples/appengine/endpoints-frameworks-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] BUILD SUCCESS
     [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 Google Service Management, an infrastructure service of Google Cloud Platform that manages other APIs and services, including services created using Cloud Endpoints.

To deploy the configuration file:

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

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

     gcloud service-management deploy target/openapi-docs/openapi.json
    

This creates a new Cloud Endpoints service with the name in the format YOUR_PROJECT_ID.appspot.com. 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 PROJECT_ID.appspot.com, 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 [example-project.appspot.com]

Running the sample locally

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

    In Linux or Mac OS:

    export ENDPOINTS_SERVICE_NAME=[YOUR_PROJECT_ID].appspot.com
    

    In Windows PowerShell:

    $Env:ENDPOINTS_SERVICE_NAME="[YOUR_PROJECT_ID].appspot.com"
    

    Replace [YOUR_PROJECT_ID] with your Cloud project ID. Do not include the square brackets.

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

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

    mvn appengine:run
    

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/endpoints-frameworks-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.

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 \
         -H "Content-Type: application/json" \
         -X POST \
         -d '{"message":"hello world"}' \
         https://[PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
    

    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 `
         "https://[PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
    

    Replace [PROJECT_ID] with your Cloud project ID. Do not include the square brackets.

    You should get a 200 response with the following data:

    {
     "message": "hello world"
    }
    

Note: App Engine may take a few minutes to respond successfully to requests. If you send a request and get back an HTTP 502, 503, or some other server error, wait a minute and try the request again.

You just deployed and tested an API in Cloud Endpoints using the Cloud Endpoints Frameworks!

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 Cloud Platform Console to shut down your Cloud Platform project:

    Go to the Projects page

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

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Endpoints Frameworks for App Engine