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
  • Official support for App Engine Flexible Environment
  • Optinally, new API management features

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:

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.48</version>
    </dependency>
  2. Add the new Endpoints Frameworks dependency:
    <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-framework</artifactId>
        <version>2.0.7</version>
    </dependency>
  3. Add the new Endpoints Frameworks plugin:
    <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>endpoints-framework-maven-plugin</artifactId>
        <version>1.0.0-beta5</version>
        <configuration>
            <!-- plugin configuration -->
        </configuration>
    </plugin>
  4. 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>

  5. Learn more about the Maven Endpoints Framework plugin goals.

Gradle

  1. Add the new Endpoints Frameworks dependency:
    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.3.0'
    
        // Endpoints Frameworks Gradle plugin
        classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.0-beta9'
      }
    }
  2. Add the new Endpoints Frameworks plugin:
    apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
  3. 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>

  4. Learn more about the Gradle Endpoints Framework 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 FooEndpointsModule extends EndpointsModule {
  @Override
  public void configureServlets() {
    bind(TestEndpoint.class).toInstance(new TestEndpoint());
    configureEndpoints("/_ah/api/*", ImmutableList.of(TestEndpoint.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.

Send feedback about...

Cloud Endpoints