Testing and Deploying an API Backend

Cloud Endpoints Frameworks v1 has been deprecated and will be shut down on August 2, 2018. We recommend that you use the latest version of this feature, which is renamed to Cloud Endpoints Frameworks for App Engine. This new version supports App Engine standard environment, provides lower latency, and has better integration with App Engine. For more details, see Migrating to 2.0.

This page describes how to test your backend API locally, how to deploy your backend API, and how to troubleshoot deployment issues.

Testing an API backend follows the typical App Engine pattern of using the development server to run the web app locally during development and incremental testing, followed by deployment to production when you are ready for real-world testing.

After you finish creating your Endpoints API and generating client libraries, you can test and deploy the API backend.

Running and testing API backends locally

To test the backend, you'll use the API Explorer, which is a tool that lets you test APIs interactively without using a client app. This tool is automatically run for you when you navigate to your backend API's subdirectory /_ah/api/explorer as we'll describe in the instructions below.

To test the API backend locally on the development server:

  1. Start a new Chrome session as described in How do I use Explorer with a local HTTP API and note the port you specify for localhost, typically 8080.

  2. Start the API backend by invoking the development app server:

    google_appengine/dev_appserver.py --port=8080 your-app-directory-path
    # Replace the port number with another one if you wish.
    # Optionally, specify --host= if you want devserver to listen to the local network.

    making sure your setting for --port= is the same port you specified above in your new Chrome session for localhost.

  3. Test the API backend in the API Explorer by navigating to http://localhost:8080/_ah/api/explorer, replacing 8080 with the port you specified in the previous steps, if different.

  4. Double-click the API you created to display the list of its methods.

  5. Click the method you wish to test, fill in any request fields as needed, then click Execute to test the method: the request will be displayed along with the response.

If you want to use curl instead of the API Explorer, you can alternatively test the API backend by sending a test request using curl. The following request makes a call to a sample Board API backend that is part of a Tic Tac Toe game:

    curl --header "Content-Type: application/json" \
         -X POST -d '{"state": "----X----"}' \

Testing clients against the backend

You can test your client against a backend API running in production App Engine at any time without making any changes. However, if you want to test your client against a backend API running on the local development server, you'll need to make changes as described below:

For more information on testing JavaScript clients locally, see Testing a JavaScript client against a local development server. For more information on testing Android clients locally, see Testing an Android client against a local development server.

Deploying an API backend

When you are satisfied that your API backend works as expected, you can deploy it to App Engine. Deploying an API backend is no different from deploying a regular App Engine app.

To deploy:

  1. Invoke the upload script as follows:

    sdk-install-directory/appcfg.py update app-directory

where sdk-install-directory is the directory where you installed the App Engine SDK, and app-directory is the directory containing your backend code. (As shown, app-directory is a subdirectory of the current directory; you could alternatively specify a full path.)

Full instructions for deploying are provided in the topic Uploading, Downloading, and Managing a Python App.

After you deploy, you can use the API Explorer to experiment with your API without using a client app by visiting


Alternatively, use the discovery service to view your API by visiting


Checking for a Successful Deployment

After you upload the API, you will see a success message if the files upload correctly. However, after the files are uploaded, App Engine does more work unpacking the API and deploying it. If there is a failure during this process, you are not informed about it. You must check the logs to determine success.

To check the logs after you deploy your API,

  1. Open the logs viewer for your project.
  2. Look at the logs nearest in time to the time you deployed. A successful API deployment results in a log that looks something like this:

    013-09-30 18:39:09.781 Endpoints: https://2-dot-test-pont.appspot.com/_ah/api/helloWorld@v2 Saved


    2013-09-30 16:07:17.987 Endpoints: https://7-dot-test2.appspot.com/_ah/api/guestbook@v1 OK

    An unsuccessful deployment has this kind of log:

     https://7-dot-test2.appspot.com/_ah/api/Guestbook@v2 ERROR

If the logs indicate a deployment failure, refer the following Troubleshooting section to see how to handle the failure.

Troubleshooting a deployment failure

Here are some common deployment error messages you might find in your application log, along with suggested remedies:

Error Remedy
Endpoints configuration not updated. Check the app's App Engine logs for errors. There is a syntax error or some other type of exception in your app that is preventing your app from starting.

Check your app's logs to narrow down the exception being thrown. Check for errors logged from the /_ah/spi/BackendService.getApiConfigs handler, which the Google Cloud Endpoints server uses to retrieve your API configuration. Here is what such a log might look like:

2014-09-04 13:03:46.531 /_ah/spi/BackendService.getApiConfigs 200 4 ms 28kb module=default version=1 - - [04 Sep/2014:13:03:46 -0700] "POST" /_ah/spi/BackendService.getApiConfigs HTTP
app_engine_release=1.9.10 apps

. . .
Endpoints configuration not updated. There are authentication requirements on the /_ah/spi handler that are preventing the Google Cloud Endpoints server from accessing the app. Remove the authentication requirements on that handler from your app's app.yaml file (see the app.yaml reference on login: admin for the lines to remove). Note: this error is not caused by setting the file to require HTTPS, as described in the secure handlers element, because this does work with Endpoints.

If you want to require authentication for your Endpoints API, follow the process described in Using Auth with Endpoints.
Endpoints configuration not updated. There is a /_ah/spi handler configured, but no Google Cloud Endpoints service was found in the app. The app.yaml file specifies a handler for /_ah/spi/.*, but the app never created an endpoints.api_server to handle a Google Cloud Endpoints API.

If you did not intend or don't want to use Google Cloud Endpoints, remove the /_ah/spi/* handler from the app.yaml file, as described in the Handlers element. Otherwise, check your application code to make sure if calls endpoints.api_server() to create a service to handle Google Cloud Endpoints requests, as described in Creating an API Server and in Writing the API in the backend tutorial.

Deploying to multiple app versions

When you deploy your backend API, you deploy it to the Cloud project ID you created for your API. This ID is the same one used by App Engine for your backend API. When you deploy, in addition to the App Engine/Cloud Project ID, you must also specify the App Engine version you deploy to. You specify the App Engine/Cloud Project ID in the application field in the app.yamlfile; you specify the application version in the version field. Notice that the App Engine app version is not the same thing as the backend API version number, which you specify in the version argument to the @endpoints.api decorator.


As shown in the figure above, you can deploy multiple API versions to the same App Engine App version. And, you can have many App Engine App versions.

Accessing backend API versions deployed to an application default version

The first App Engine version that you deploy your backend API to is the default version. This version runs at the URL http://your_app_id.appspot.com. All of the backend API versions deployed to that App Engine app version can be accessed using that URL.

The default version remains the default version until you explicitly change it. To change the default version:

  1. Open the versions page for your project.
  2. Select the version you want as the default version and click Make Default.

Accessing backend API versions deployed to non-default application versions

If you need to access API versions that are not deployed to the default App Engine app version, you use a version-specific URL.

To access backend API versions that are deployed to non-default App Engine versions of your app, you must include the version specifier in the URL, like this: https://version-dot-your_app_id.appspot.com. For example, suppose your default app version is 1, but you want to access a backend API version deployed to App Engine app version 2; you would use this URL: https://2-dot-your_app_id.appspot.com.

Accessing backend API versions deployed to non-default modules

If you need to access API versions that are not deployed to the default App Engine module, you would use a version-specific URL using the dot syntax as follows:


Managing your backend API versions

In managing your API versions, consider these recommendations:

  • When you want to introduce an incremental, but non-breaking change, keep the API version constant and deploy over the existing API.
  • When you introduce a breaking change to your API, increment the API version.
  • For additional protection, increment the App Engine app version as well and then deploy the new API version to that new App Engine app version. This lets you use the built-in flexibility of App Engine to quickly switch between App Engine versions and serve from the old working versions if you run into unexpected problems.

The following table is an illustration of cascading backend API versions to different App Engine app versions:

App Version backend API version
  • v1 --> v1 (2) --> v1 (n)
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
  • v1 (n)
  • v2 (n)
  • v3 --> v3 (2) --> v3 (n)

As shown in the table, incremental, non-breaking updates to v1 of the API are rolled out, each overwriting the previous version. When breaking changes are introduced, the API version is incremented to v2 and it is deployed to a new App Engine app version. That allows you to switch back to the previous app version if needed.

In the table, notice that app version 2 supports both the latest v1 version and the new v2 version of your API. If you don't delete the existing v1 code from your project, deploying the project will result in both v2 and vl (n) of your API being deployed to App version 2.

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

Send feedback about...

Cloud Endpoints Frameworks for App Engine