Migrating to Endpoints Frameworks for App Engine

This page describes migrating an existing Cloud Endpoints 1.0 app to Endpoints Frameworks for App Engine in Java. Note that this page refers to Cloud Endpoints 1.0 as Cloud Endpoints Frameworks version 1.0 and new Endpoints Frameworks for App Engine as Endpoints Frameworks version 2.0.

Benefits

The new framework brings a number of benefits, including:

  • Reduced request latency
  • Better integration with App Engine features (such as custom domains)
  • Official support for Guice configurations
  • Optionally, new API management features

Endpoints Frameworks 2.0 does not affect the interfaces to your API. Existing clients continue to work after migration without any client-side code changes.

Currently excluded features and tools

The following features are not currently available. If you require any of these, migration is currently not recommended.

  • JSON-RPC protocol, which is required for legacy iOS clients
  • Automatic ETags
  • Automatic kind fields
  • IDE integration
  • fields partial responses

In addition, the following tools are not currently supported for version 2.0:

  • Android Studio support for Cloud Endpoints 1.0
  • Android Studio code validation and quick fixes for Cloud Endpoints 1.0

Migrating to Endpoints Frameworks 2.0 using a Discovery Document

Endpoints Frameworks 2.0 has moved to Maven artifacts in group com.google.endpoints. The base required JAR is in the endpoints-framework artifact. If you wish to use Guice configuration, add the endpoints-framework-guice artifact.

The following instructions provide an example of how to migrate from Cloud Endpoints Frameworks 1.0 to Endpoints Frameworks 2.0 using a Discovery Document:

To migrate using Maven or Gradle:

Maven

  1. If you are using Maven, remove the legacy dependency, which is the appengine-endpoints artifact:
    <dependency>
          <groupId>com.google.appengine</groupId>
          <artifactId>appengine-endpoints</artifactId>
          <version>1.9.53</version>
    </dependency>
  2. Add the new Endpoints Frameworks dependency:
    <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-framework</artifactId>
        <version>2.0.9</version>
    </dependency>
  3. Add the new Endpoints Frameworks plugin and define the hostname for a generated discovery document:
    <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>endpoints-framework-maven-plugin</artifactId>
        <version>1.0.2</version>
        <configuration>
            <!-- plugin configuration -->
            <hostname>YOUR-PROJECT-ID.appspot.com</hostname>
        </configuration>
    </plugin>
  4. Add the new App Engine Maven plugin:
    <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>appengine-maven-plugin</artifactId>
        <version>1.3.2</version>
        <configuration>
            <!-- deploy configuration -->
        </configuration>
    </plugin>
  5. Update the API entry point in your project web.xml file:
    • Rename all occurrences of SystemServiceServlet to EndpointsServlet
    • Replace all occurences of the path /_ah/spi/ to the new required path /_ah/api/

      The following code tabs show the contents of the web.xml before and after migration:

      Before Migration

      Cloud Endpoints Frameworks 1.0 web.xml:

      <servlet>
          <servlet-name>SystemServiceServlet</servlet-name>
          <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
          <init-param>
              <param-name>services</param-name>
              <param-value>com.example.helloendpoints.Greetings</param-value>
          </init-param>
          <init-param>
              <param-name>restricted</param-name>
              <param-value>false</param-value>
          </init-param>
      </servlet>
      <servlet-mapping>
          <servlet-name>SystemServiceServlet</servlet-name>
          <url-pattern>/_ah/spi/*</url-pattern>
      </servlet-mapping>

      After Migration

      Cloud Endpoints Frameworks 2.0 web.xml:

      <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.helloendpoints.Greetings</param-value>
          </init-param>
          <init-param>
              <param-name>restricted</param-name>
              <param-value>false</param-value>
          </init-param>
      </servlet>
      <servlet-mapping>
          <servlet-name>EndpointsServlet</servlet-name>
          <url-pattern>/_ah/api/*</url-pattern>
      </servlet-mapping>

  6. After modifying dependencies clean the project using:
    mvn clean
  7. You can generate a discovery document by using:
    mvn endpoints-framework:discoveryDocs
    Learn more about the Maven Endpoints Framework plugin goals.
  8. You can deploy a project by using:
    mvn appengine:deploy
    Learn more about the Maven App Engine plugin goals

Gradle

  1. Add the new Endpoints Frameworks dependency:
    compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'
  2. Add the new App Engine and Endpoints Frameworks plugins:
    buildscript {    // Configuration for building
      repositories {
        mavenCentral()
        jcenter()    // Bintray's repository - a fast Maven Central mirror & more
      }
      dependencies {
        // App Engine Gradle plugin
        classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.0.2'
    
        // Endpoints Frameworks Gradle plugin
        classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.3.3'
      }
    }
  3. Apply the new App Engine and Endpoints Frameworks plugins:
    apply plugin: 'com.google.cloud.tools.appengine'
    apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
  4. Define the hostname endpoint for generated discovery documents:
    endpointsServer {
      // Endpoints Framework Plugin server-side configuration
      hostname = "YOUR-PROJECT-ID.appspot.com"
    }
  5. Update the API entry point in your project web.xml file:
    • Rename all occurrences of SystemServiceServlet to EndpointsServlet
    • Replace all occurences of the path /_ah/spi/ to the new required path /_ah/api/

      The following code tabs show the contents of the web.xml before and after migration:

      Before Migration

      Cloud Endpoints Frameworks 1.0 web.xml:

      <servlet>
          <servlet-name>SystemServiceServlet</servlet-name>
          <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
          <init-param>
              <param-name>services</param-name>
              <param-value>com.example.helloendpoints.Greetings</param-value>
          </init-param>
          <init-param>
              <param-name>restricted</param-name>
              <param-value>false</param-value>
          </init-param>
      </servlet>
      <servlet-mapping>
          <servlet-name>SystemServiceServlet</servlet-name>
          <url-pattern>/_ah/spi/*</url-pattern>
      </servlet-mapping>

      After Migration

      Cloud Endpoints Frameworks 2.0 web.xml:

      <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.helloendpoints.Greetings</param-value>
          </init-param>
          <init-param>
              <param-name>restricted</param-name>
              <param-value>false</param-value>
          </init-param>
      </servlet>
      <servlet-mapping>
          <servlet-name>EndpointsServlet</servlet-name>
          <url-pattern>/_ah/api/*</url-pattern>
      </servlet-mapping>

  6. After modifying dependencies clean the project using:
    gradle clean
  7. You can generate a discovery document by using:
    gradle endpointsDiscoveryDocs
    Learn more about the Gradle Endpoints Framework plugin tasks
  8. You can deploy a project by using:
    gradle appengineDeploy
    Learn more about the Gradle App Engine plugin tasks

Using Guice to configure Cloud Endpoints Java Framework

If you wish to use Guice, declare a new module that extends EndpointsModule, and configure it, as follows:

public class EchoEndpointModule extends EndpointsModule {
  @Override
  public void configureServlets() {
    super.configureServlets();

    bind(ServiceManagementConfigFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(ServiceManagementConfigFilter.class);

    Map<String, String> apiController = new HashMap<String, String>();
    apiController.put("endpoints.projectId", "YOUR-PROJECT-ID");
    apiController.put("endpoints.serviceName", "YOUR-PROJECT-ID.appspot.com");

    bind(GoogleAppEngineControlFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(GoogleAppEngineControlFilter.class, apiController);

    bind(Echo.class).toInstance(new Echo());
    configureEndpoints("/_ah/api/*", ImmutableList.of(Echo.class));
  }
}

Adding Endpoints API Management

Cloud Endpoints Frameworks 2.0 also allows you to turn on API management features, including:

  • API key management
  • API sharing
  • User authentication
  • API metrics
  • API logs

To get started using these and other Cloud Endpoints Frameworks 2.0 features, navigate to the Endpoints Frameworks for App Engine using Java page.

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