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

Feature overview

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
  • CORS (for JavaScript callers not using Google JavaScript client library)
  • 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
  • Automatic kind fields
  • IDE integration
  • fields partial responses
  • Automatic PATCH API method creation

Migrating from Cloud Endpoints version 1.0

To migrate from version 1.0:

  1. Create a subfolder named /lib in your application main directory (for example, /my-app./lib/).

  2. Invoke the following install command from your application main directory:

     pip install -t lib google-endpoints --ignore-installed
  3. Remove the entries - name: endpoints and version 1.0 from your application app.yaml file under the libraries section. For example:

    - name: endpoints   #Remove
      version: 1.0      #Remove
  4. In the libraries section in app.yaml, add the following:

    - name: pycrypto
      version: 2.6
    - name: ssl
      version: 2.7.11
  5. In the handlers section in app.yaml, change the url directive from - url: /_ah/spi/.* to - url: /_ah/api/.*.

  6. In the root directory of your application, create/modify a file named appengine_config.py to include the following:

    from google.appengine.ext import vendor
  7. 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 echo with version 2.1.0 would have a path like /echo/v2. If you update the echo API to version 2.2.0 and 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 echo API to version 3.0.0 (because you are deploying a breaking change), the path is changed to /echo/v3.

  8. Redeploy your Endpoints application.

Verifying a new deployment

You can verify that the new framework is serving traffic:

  1. Send some requests to the new deployment.
  2. Visit the Stackdriver logging page for your project.
    View Google App Engine Application Logs
  3. 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 sent to /_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: ...

Error message: ImportError: cannot import name locked_file

This happens if your dependencies contain a version of the oauth2client library that is incompatible with App Engine. See the known issue.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine
Need help? Visit our support page.