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:
- Make sure that the gcloud CLI is authorized to access your data and services on Google Cloud:
gcloud auth login
- Use application default credentials:
gcloud auth application-default login
- Install the Google Cloud SDK
app-engine-java
component:gcloud components install app-engine-java
- Update to the latest version of the Google Cloud SDK and all components:
gcloud components update
- Make sure that the gcloud CLI is authorized to access your data and services on Google Cloud:
Migrate using Maven or Gradle
Maven
- Remove the legacy dependency, which is the
appengine-endpoints
artifact: - Add the new Endpoints Frameworks dependency:
- Add the new Endpoints Frameworks plugin and define the hostname for a generated discovery document:
- Add the new App Engine Maven plugin:
- Update the API entry point in your project
web.xml
file:- Rename all occurrences of
SystemServiceServlet
toEndpointsServlet
- 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.0web.xml
:After migration
Endpoints Frameworks version 2.0web.xml
: - Rename all occurrences of
- After modifying dependencies clean the projec:
mvn clean
- You can generate a discovery document:
Learn more about the Maven Endpoints Frameworks plugin goals.mvn endpoints-framework:discoveryDocs
- You can deploy a project:
mvn appengine:deploy
Learn more about the Maven App Engine plugin goals.
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:
- Add the new App Engine and Endpoints Frameworks plugins:
- Apply the new App Engine and Endpoints Frameworks plugins:
- Define the hostname endpoint for generated discovery documents:
- Update the API entry point in your project
web.xml
file:- Rename all occurrences of
SystemServiceServlet
toEndpointsServlet
- 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.0web.xml
:After migration
Endpoints Frameworks version 2.0web.xml
: - Rename all occurrences of
- After modifying dependencies clean the project using:
gradle clean
- You can generate a discovery document by using:
Learn more about the Gradle Endpoints Frameworks plugin tasksgradle endpointsDiscoveryDocs
- You can deploy a project by using:
gradle appengineDeploy
Learn more about the Gradle App Engine plugin tasks.
Using Guice to configure Endpoints Frameworks for Java
If you wish to use Guice:
- Add the new Endpoints Frameworks Guice dependency:
Maven
Gradle
- Declare a new module that extends
EndpointsModule
, and configure it, as follows:
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.
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
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.