Setting Up a Development Environment

This page describes how to set up your development environment to build and deploy your backend API using Cloud Endpoints Frameworks for the App Engine standard environment. This page uses the Endpoints Framework v2 skeleton code sample to explain the basic software and components you need to get started.

You might want to use the endpoints-skeleton-archetype or the hello-endpoints-archetype described in Using Apache Maven and the App Engine Plugin (Cloud SDK-based) to create a new Endpoints Frameworks v2 project.

To get a better understanding of the steps required to deploy a sample API using Endpoints Frameworks, see the tutorial Getting Started with Endpoints Frameworks on App Engine.

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 Cloud Platform project.

    Go to the Manage resources page

  3. Enable billing for your project.

    Enable billing

  4. Note the Google Cloud Platform (GCP) 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. Install either Maven or Gradle:

    Maven

    1. Download Apache Maven version 3.3.9 or greater
    2. Install and configure Maven for your local development environment.

    Gradle

  3. Download the Google Cloud SDK. Run the following commands after downloading the Cloud SDK:
    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
      
  4. 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. See App Engine Locations for a list of regions.
    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] \
        --region=[YOUR_REGION]
      

Getting the Endpoints Frameworks skeleton sample

The Endpoints Framework v2 skeleton sample contains the necessary build scripts for Maven and Gradle. It also contains the required files to get started creating your first API.

  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 Endpoints Framework skeleton sample:

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

    The sample has the following directory structure:

    Endpoints Frameworks Skeleton Sample Layout

    • MyApi.java contains an empty class that you can use to get started writing your API. See the echo example for sample code to help you get started.

    • web.xml is a standard file that is used to configure a servlet.

    • appengine-web.xml defines information that is required to deploy the API to the App Engine standard environment using Java 8.

    • pom.xml contains project and configuration information used by Maven to build the project and deploy the API to App Engine.

    • build.gradle contains project and configuration information used by Gradle to build the project and deploy the API to App Engine.

Configuring the build files

This section describes the Maven pom.xml and Gradle build.gradle files included in the sample code. Except for entering your GCP project ID so that it can be used in the hostname (described below), the build files are ready for you to use to get started creating your API.

About the minimum configuration

This section describes the minimum configuration needed in your build file.

Maven

Minimum dependencies

The following shows the minimum dependencies required in your pom.xml to get started:

<dependencies>
    <!-- Compile/runtime dependencies -->
    <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-framework</artifactId>
        <version>2.0.9</version>
    </dependency>
    <dependency>
        <groupId>com.google.appengine</groupId>
        <artifactId>appengine-api-1.0-sdk</artifactId>
        <version>1.9.59</version>
    </dependency>
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
        <type>jar</type>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>javax.inject</groupId>
        <artifactId>javax.inject</artifactId>
        <version>1</version>
    </dependency>
</dependencies>

Apply plugins

The following plugins are applied to enable them.

<build>
    <!-- for hot reload of the web application-->
    <outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/classes</outputDirectory>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <version>2.6</version>
            <configuration>
                <webResources>
                    <resources>
                        <directory>${basedir}/src/main/webapp/WEB-INF</directory>
                        <filtering>true</filtering>
                        <targetPath>WEB-INF</targetPath>
                    </resources>
                </webResources>
            </configuration>
        </plugin>
        <plugin>
            <groupId>com.google.cloud.tools</groupId>
            <artifactId>appengine-maven-plugin</artifactId>
            <version>1.3.2</version>
            <configuration>
                <!-- deploy configuration -->
            </configuration>
        </plugin>
        <plugin>
            <groupId>com.google.cloud.tools</groupId>
            <artifactId>endpoints-framework-maven-plugin</artifactId>
            <version>1.0.2</version>
            <configuration>
                <!-- plugin configuration -->
                <!--
                     You must replace YOUR_PROJECT_ID with your
                     Google Cloud Project Id
                -->
                <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle

Plugin dependencies

The following shows the plugins required to build your API:

buildscript {
  repositories {
    mavenCentral()
  }

  dependencies {
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.3'
  }
}

Apply plugins

The following plugins are applied to enable them in your Gradle build script:

apply plugin: 'java'
apply plugin: 'war'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
apply plugin: 'com.google.cloud.tools.appengine'

  • The java plugin adds Java-specific compilation and build steps to your project.
  • The war plugin extends the java plugin to add support for assembling a web application.
  • The endpoints-framework-server plugin provides server-side support to the Endpoints Framework Gradle plugin.
  • The appengine plugin is required to run the API on App Engine.

Project dependencies

The following dependencies are used by the project:

dependencies {
    compile 'com.google.endpoints:endpoints-framework:2.0.9'
    compile 'com.google.appengine:appengine-api-1.0-sdk:1.9.59'

    compile 'javax.inject:javax.inject:1'
    compileOnly 'javax.servlet:javax.servlet-api:3.1.0'
}

Defining the hostname for your service

Endpoints Frameworks uses DNS-compatible names to uniquely identify services. Because GCP project IDs are guaranteed to be globally unique, you should use your GCP project ID as part of your API's service name.

You must add your GCP project ID to the build files to configure the hostname for your service. The hostname should be in the following format:

YOUR_PROJECT_ID.appspot.com

When you deploy the API to App Engine, a DNS entry with a name in the format YOUR_PROJECT_ID.appspot.com is created automatically. The hostname is both the name of the Endpoints service and the domain name that you use to send requests to your API.

Maven

<plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>endpoints-framework-maven-plugin</artifactId>
    <version>1.0.2</version>
    <configuration>
        <!-- plugin configuration -->
        <!--
             You must replace YOUR_PROJECT_ID with your
             Google Cloud Project Id
        -->
        <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
    </configuration>
</plugin>

In the hostname field, replace YOUR_PROJECT_ID with your GCP project ID.

Gradle

// You must replace YOUR_PROJECT_ID with your Google Cloud Project Id
def projectId = 'YOUR_PROJECT_ID'

endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "${projectId}.appspot.com"
}

Set the variable projectID to your GCP project ID. For example: def projectId = 'example-project-1865'

Configuring the Endpoints servlet

The Endpoints servlet handles incoming requests and forwards them to the backend service running on App Engine. The Endpoints servlet is required for your API to be managed by Cloud Endpoints.

For more information about web.xml, see The Deployment Descriptor: web.xml.

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <!-- Wrap the backend with Endpoints Frameworks v2. -->
    <servlet>
        <servlet-name>EndpointsServlet</servlet-name>
        <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
        <init-param>
            <param-name>services</param-name>
            <param-value>com.example.skeleton.MyApi</param-value>
        </init-param>
    </servlet>
    <!-- Route API method requests to the backend. -->
    <servlet-mapping>
        <servlet-name>EndpointsServlet</servlet-name>
        <url-pattern>/_ah/api/*</url-pattern>
    </servlet-mapping>
</web-app>

Configuring your App Engine deployment

The appengine-web.xml file is used to define the App Engine standard environment configuration when the API is deployed. See appengine-web.xml Reference for more information.

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <runtime>java8</runtime>
    <threadsafe>true</threadsafe>

    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
    </system-properties>
</appengine-web-app>

What's Next?

Send feedback about...

Cloud Endpoints Frameworks for App Engine