Cloud Endpoints Frameworks was formerly called Endpoints. To distinguish between the two versions, this page refers to the new version as Endpoints Frameworks version 2.0, and the older version as Endpoints version 1.0. This page describes how to migrate an Cloud Endpoints version 1.0 application to Endpoints Frameworks version 2.0. The migration consists of a library change and an application configuration change, but you don't have to make any changes to your code.
Endpoints version 2.0 brings a number of benefits, including:
- Reduced request latency.
- Better integration with App Engine features, such as custom domains.
- 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.
The following features are backward compatible with Endpoints version 1.0:
- JSON-REST protocol, which is used by all Google client libraries
- Discovery service
- All existing authentication features (OAuth2/OpenID Connect)
- Client library support for generated clients
- API Explorer
Traffic splitting is unavailable.
Currently excluded features
The following features are unavailable. 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
- IDE integration
- Automatic PATCH API method creation
Migrating from Endpoints version 1.0
To migrate from version 1.0:
Create a subfolder named
/libin your application's main directory.
Install the library from your application's main directory:
pip install -t lib google-endpoints --ignore-installed
- name: endpointsand
version 1.0entries from your application's
app.yamlfile under the
librariessection. For example:
libraries: - name: endpoints #Remove version: 1.0 #Remove
librariessection in the
app.yamlfile, add the following:
libraries: - name: pycrypto version: 2.6 - name: ssl version: 2.7.11
Endpoints Frameworks requires these versions of the
handlerssection in the
app.yamlfile, change the
- url: /_ah/spi/.*to
- url: /_ah/api/.*.
In the root directory of your application, create or modify a file named
appengine_config.pyto include the following:
from google.appengine.ext import vendor vendor.add('lib')
Check your API version string. Your version string, specified in the
@endpoints.api(version='v1', ...)decorator, appears in your API's path. If you specify a version string compatible with the SemVer standard, only the major version number appears in your API's path when you deploy your API. For example, an API called
2.1.0would have a path such as
/echo/v2. If you update the
echoAPI to version
2.2.0and deploy a backwards-compatible change, the path remains
/echo/v2. This allows you to update the API version number when you make a backwards-compatible change without breaking existing paths for your clients. But if you update the
echoAPI to version
3.0.0(because you are deploying a breaking change), the path is changed to
Redeploy your Endpoints Frameworks application.
Verifying a new deployment
To verify that the new framework is serving traffic:
- Send some requests to the new deployment.
- Visit the Stackdriver Logging page for your project.
- If requests are shown with having 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 version 1.0 proxy is still serving requests.
Adding API management
Endpoints Frameworks version 2.0 adds API management features, including:
- API key management
- API sharing
- User authentication
- API metrics
- API logs
To get started, go to the Getting started with Endpoints Frameworks for Python page.
This section describes common erratic behaviors when migrating to Endpoints Frameworks version 2.0 and suggested solutions.
404 errors, but API Explorer still lists APIs correctly
You are required to remove the old version 1.0 Endpoints
configuration when migrating to Endpoints Frameworks version 2.0. If
the old configuration is still present in the application's configuration, the
Endpoints service continues to treat the app as a version 1.0
app. You might see requests in your App Engine logs sent to
which result in
HTTP 404 errors sent to the client.
Remove the following lines, from the
app.yamlfile if they are present:
handlers: - url: /_ah/spi/.* script: ...
Make sure the
handlerssection in your
app.yamlfile has the correct path:
handlers: # The endpoints handler must be mapped to /_ah/api. - url: /_ah/api/.* script: ...
ImportError: cannot import name locked_file
This happens if your dependencies contain a version of the
library that is incompatible with App Engine. See the