Migrating to Cloud Endpoints Frameworks 2.0 for App Engine

This document describes how to migrate an existing Cloud Endpoints 1.0 app to version 2.0 of the frameworks in Java.

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
  • 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 version 2.0

Version 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. To migrate from version 1.0 to version 2.0:

  1. Update your dependency to use the new artifact. In Maven, this looks something like below:

    com.google.endpoints endpoints-framework 2.0.0-beta.5

  2. Remove the legacy dependency, which is the appengine-endpoints artifact.

  3. Update the API entry point in your project web.xml file:

    1. Rename all occurrences of SystemServiceServlet to EndpointsServlet.
    2. Replace all occurences of the path /_ah/spi/* to the new required path /_ah/api/*

A sample web.xml migration is shown below:

Version 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.google.testapi.TestEndpoint,com.google.waxapi.WaxEndpoint</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>

Cloud Endpoints Java Framework version 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.google.testapi.TestEndpoint,com.google.waxapi.WaxEndpoint</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>

Using Guice to configure Cloud Endpoints Java Framework

If you wish to use Guice to, 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

The new version of Endpoints adds API management features, including:

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

To get started, navigate to the Endpoints Frameworks for App Engine Java page.

Send feedback about...

App Engine standard environment for Java