This document describes how to migrate an existing Cloud Endpoints 1.0 app to version 2.0 of the frameworks in Python.
The Cloud Endpoints Frameworks 2.0 for App Engine, was formerly called Cloud Endpoints in version 1.0. This document also describes the migration process for developers wishing to migrate an existing Cloud Endpoints version 1.0 for Python project to the new 2.0 framework. This migration consists of a library change and an app configuration change but no code changes are required.
The new framework 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 2.0 does not affect the interfaces to your API. Existing clients continue to work after migration without any client-side code changes.
This Beta release contains only a subset of features expected for the general release of Cloud Endpoints Python Framework 2.0. The feature subset includes the following features that are backward compatible with Cloud 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
The following features are not currently available:
- Traffic splitting
Currently excluded features
The following features are not 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 v2 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 Cloud Endpoints version 1.0
To migrate from version 1.0:
Create a subfolder named
/libin your application main directory (for example,
Invoke the following install command from your application main directory:
pip install -t lib google-endpoints --ignore-installed
Remove the entries
- name: endpointsand
version 1.0from your application
app.yamlfile under the
librariessection. For example:
libraries: - name: endpoints #Remove version: 1.0 #Remove
app.yaml, add the following:
libraries: - name: pycrypto version: 2.6 - name: ssl version: 2.7.11
app.yaml, change the
- url: /_ah/spi/.*to
- url: /_ah/api/.*.
In the root directory of your application, create/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) will appear in your API's path. If you specify a version string compatible with the SemVer standard, only the major version number will appear in your API's path. when you deploy your API. So, for example, an API called
2.1.0would have a path like
/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 application.
Verifying a new deployment
You can verify that the new framework is serving traffic:
- Send some requests to the new deployment.
- Visit the Stackdriver logging page for your project.
View Google App Engine Application Logs
- If requests are shown with having paths beginning with
/_ah/api, then Endpoints Frameworks 2.0 is now serving your API. The logs should not show any requests with paths beginning with
/_ah/spi. These requests indicate that the Cloud Endpoints 1.0 proxy is still serving requests.
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 Python page.
This section describes common erratic behaviors when migrating to Endpoints Frameworks 2.0 and suggested solutions.
API returns 404 errors, but API Explorer still lists APIs correctly
You are required to remove the old v1 Endpoints configuration when migrating to
Endpoints Frameworks v2. If the old configuration is still present in the app
configuration, the Endpoints service will continue to treat the app as a v1 app.
You may see requests in your App Engine logs being
/_ah/spi, which result in HTTP 404 errors being sent to the client.
Remove the following lines, from
app.yaml if they are present:
- url: /_ah/spi/.* 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