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 Frameworks version 2.0 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 (Google Cloud CLI-based) to create a new Endpoints Frameworks version 2.0 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

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

1. Make a note of the Google Cloud project ID because it is needed later.

Installing and configuring required software

1. If you don't have Java 8 installed, download the Java Development Kit (JDK) from Oracle's 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

   • Install Gradle .
3. Download and initialize the Google Cloud CLI .
4. Run the following commands:
   1. Make sure that the gcloud CLI is authorized to access your data and services on Google Cloud:

      gcloud  
      auth  
      login

   2. Use application default credentials:

      gcloud  
      auth  
      application-default  
      login

   3. Install the Google Cloud SDK app-engine-java component:

      gcloud  
      components  
      install  
      app-engine-java

   4. Update to the latest version of the Google Cloud SDK and all components:

      gcloud  
      components  
      update

5. Create an App Engine application:
   1. Set the default project to your Google Cloud project ID:

      gcloud  
      config  
       set 
        
      project  
       YOUR_PROJECT_ID 
      

      Replace YOUR_PROJECT_ID with your Google Cloud project ID. If you have other Google Cloud projects, and you want to use gcloud to manage them, see Managing gcloud CLI configurations .

   2. Select the region where you want to create your App Engine application. See App Engine locations for a list of regions.
   3. Create an App Engine application. Replace YOUR_PROJECT_ID with your Google Cloud project ID and YOUR_REGION with the region that you want the App Engine application created in.

        
       gcloud 
        
       app 
        
       create 
        
       \ 
        
       -- 
       project 
       = 
        YOUR_PROJECT_ID 
       
        
       \ 
        
       -- 
       region 
       = 
        YOUR_REGION 
       
      

Getting the Endpoints Frameworks skeleton sample

The Endpoints Frameworks version 2.0 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 Frameworks skeleton sample:

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

   The sample has the following directory structure:

   

   • 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 by 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 Google Cloud project ID so that it can be used in the hostname, the build files are ready for you to get started creating your API.

About the minimum configuration

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

 <dependencies>  
<!--  
Compile/runtime  
dependencies  
-->  
<dependency>  
<groupId>com.google.endpoints</groupId>  
<artifactId>endpoints-framework</artifactId>  
<version>2.2.2</version>  
</dependency>  
<dependency>  
<groupId>com.google.appengine</groupId>  
<artifactId>appengine-api-1.0-sdk</artifactId>  
<version>2.0.23</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> 

 <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>3.4.0</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>2.5.0</version>  
<configuration>  
<!--  
deploy  
configuration  
-->  
<projectId>GCLOUD_CONFIG</projectId>  
<version>GCLOUD_CONFIG</version>  
</configuration>  
</plugin>  
<plugin>  
<groupId>com.google.cloud.tools</groupId>  
<artifactId>endpoints-framework-maven-plugin</artifactId>  
<version>2.1.0</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> 

  buildscript 
  
 { 
  
 repositories 
  
 { 
  
 mavenCentral 
 () 
  
 } 
  
 dependencies 
  
 { 
  
 classpath 
  
 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.1.0' 
  
 classpath 
  
 'com.google.cloud.tools:appengine-gradle-plugin:2.5.0' 
  
 } 
 } 
 

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

  dependencies 
  
 { 
  
 compile 
  
 'com.google.endpoints:endpoints-framework:2.2.2' 
  
 compile 
  
 'com.google.appengine:appengine-api-1.0-sdk:2.0.23' 
  
 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 Google Cloud project IDs are guaranteed to be globally unique, you should use your Google Cloud project ID as part of your API's service name.

You must add your Google Cloud 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 Cloud Endpoints service and the domain name that you use to send requests to your API.

 <plugin>  
<groupId>com.google.cloud.tools</groupId>  
<artifactId>endpoints-framework-maven-plugin</artifactId>  
<version>2.1.0</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> 

  // 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" 
 } 
 

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

• Write and annotate your backend API code .
• Learn more about annotations .
• Add API management .
• Deploy and test your API .
• Learn more about supported parameter and return types .