Migrating to Cloud Endpoints Frameworks version 2.0 for App Engine

This page describes migrating an existing Cloud Endpoints version 1.0 application to Endpoints Frameworks for App Engine 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.
Optionally, new API management features.

Endpoints Frameworks version 2.0 doesn't 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 aren't currently available. If you require any of these, please submit a feature request.

JSON-RPC protocol, which is required for legacy iOS clients. To create iOS clients for your Endpoints Frameworks version 2.0 API, we recommend that you use Google APIs Objective-C client library for REST APIs.
Automatic ETags
Automatic kind fields
IDE integration
fields partial responses
Automatic PATCH API method creation

In addition, Android Studio support for Endpoints version 1.0 isn't currently supported for version 2.0.

Migrating to Endpoints Frameworks version 2.0

Endpoints Frameworks 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.

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

Download and initialize the Google Cloud CLI.
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
```

Migrate using Maven or Gradle

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>

Add the new Endpoints Frameworks dependency:

<dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.1</version>
</dependency>

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>

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>

Note: The old App Engine Maven plugin, with group com.google.appengine, is incompatible with the Endpoints Frameworks plugin. You must use the new version.

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

Rename all occurrences of SystemServiceServlet to EndpointsServlet
Replace all occurrences of the path /_ah/spi/ to the new required path /_ah/api/

The following shows the contents of the web.xml before and after migration:

Before migration

Endpoints Frameworks 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.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

Endpoints Frameworks 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.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>

After modifying dependencies clean the projec:
```
mvn clean
```
You can generate a discovery document:
```
mvn endpoints-framework:discoveryDocs
```
Learn more about the Maven Endpoints Frameworks plugin goals.
You can deploy a project:
```
mvn appengine:deploy
```
Learn more about the Maven App Engine plugin goals.

Note: When migrating, you must deploy to a new App Engine version. This is done automatically if you don't specify a version. See Known issues.

Gradle

Remove the legacy dependency, which is the appengine-endpoints artifact:

compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

Add the new Endpoints Frameworks dependency:

compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

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.3.3'

    // Endpoints Frameworks Gradle plugin
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
  }
}

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'

Define the hostname endpoint for generated discovery documents:

endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "YOUR-PROJECT-ID.appspot.com"
}

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

Rename all occurrences of SystemServiceServlet to EndpointsServlet
Replace all occurrences of the path /_ah/spi/ to the new required path /_ah/api/

The following shows the contents of the web.xml before and after migration:

Before migration

Endpoints Frameworks 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.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

Endpoints Frameworks 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.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>

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

Note: When migrating, you must deploy to a new App Engine version. This is done automatically if you don't specify a version. See Known issues.

Using Guice to configure Endpoints Frameworks for Java

If you wish to use Guice:

Add the new Endpoints Frameworks Guice dependency:

Maven

<dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework-guice</artifactId>
    <version>2.2.1</version>
</dependency>

Gradle

compile 'com.google.endpoints:endpoints-framework-guice:2.0.9'

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));
  }
}

Verifying a new deployment

You can verify that the new framework is serving traffic:

Send some requests to the new deployment.
In the Google Cloud console, go to the Logging > Logs Explorer page.

Go to the Logs Explorer page
If requests are shown with paths beginning with /_ah/api, then Endpoints Frameworks version 2.0 is now serving your API. The logs shouldn't show any requests with paths beginning with /_ah/spi. These requests indicate that the Endpoints Frameworks version 1.0 proxy is still serving requests.

Adding Endpoints API management

Endpoints Frameworks version 2.0 also lets you turn on API management features, including:

API key management
API sharing
User authentication
API metrics
API logs

To get started using these features, see Adding API management.

Troubleshooting

This section describes common erratic behaviors when migrating to Endpoints Frameworks version 2.0 and suggested solutions.

API returns `404` errors, but API Explorer still lists APIs correctly

You are required to remove the old Endpoints Frameworks version 1.0 configuration when migrating to Endpoints Frameworks version 2.0. If the old configuration is still present in the application configuration, the Endpoints service continues to treat the app as a version 1.0 app. You may see requests in your App Engine logs sent to /_ah/spi, which result in HTTP 404 errors sent to the client.

Remove the following lines from your web.xml file, if they are present:

<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>...</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

Make sure your web.xml file contains the following:

<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

API is throwing reflection errors

You must package only the endpoints-framework artifact into your application, not the old appengine-endpoints JAR. If you deploy an application with both JARs, you might run into reflection errors or runtime type errors, such as NoClassDefFoundError, NoSuchMethodError, and ClassCastException. Remove the following lines from your build file, if they are present:

Maven

<dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>

Gradle

compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

In addition, if any of your other dependencies depend on older versions of Guava, this can also manifest as a missing TypeToken method. You must ensure that you use Guava v19 or use the endpoints-framework-all artifact, which shadows dependencies.

Client library sources don't compile

If you see an error such as, method does not override or implement a method from a supertype, or cannot find symbol method setBatchPath(String), then your client application likely depends on an old version of the Google Java client library. You must ensure that your google-api-client artifact is 1.23.0 or higher.

Maven

<dependency>
    <groupId>com.google.api-client</groupId>
    <artifactId>google-api-client</artifactId>
    <version>1.23.0</version>
</dependency>

Gradle

compile group: 'com.google.api-client', name: 'google-api-client', version: '1.23.0'

Issues with JPA/JDO Datanucleus enhancement

Maven

The new Google Cloud CLI-based App Engine Maven plugin doesn't support Datanucleus enhancement of any type. If your project uses the Datanucleus JDO or JPA enhancement support from the old plugin, you must configure the third-party Datanucleus Maven plugin separately when you migrate. See the following for more information:

Gradle

If your project uses the gradle-appengine-plugin JPA/JDO Datanucleus enhancement, you must manually configure Datanucleus enhancement after switching to the new gcloud CLI-based Gradle plugin. See an example from Stackoverflow.

Migrating to Cloud Endpoints Frameworks version 2.0 for App Engine

Benefits

Currently excluded features and tools

Migrating to Endpoints Frameworks version 2.0

Migrate using Maven or Gradle

Maven

Before migration

After migration

Gradle

Before migration

After migration

Using Guice to configure Endpoints Frameworks for Java

Maven

Gradle

Verifying a new deployment

Adding Endpoints API management

Troubleshooting

API returns 404 errors, but API Explorer still lists APIs correctly

API is throwing reflection errors

Maven

Gradle

Client library sources don't compile

Maven

Gradle

Issues with JPA/JDO Datanucleus enhancement

Maven

Gradle

API returns `404` errors, but API Explorer still lists APIs correctly