Google Cloud Platform

Remote API for Python

The Python SDK includes a library called Remote API that lets you transparently access App Engine services from any Python application. For example, you can use Remote API to access a production datastore from an app running on your local machine.

Enabling Remote API

You can enable the Remote API using either the builtins directive, which will make the Remote API available on the default path, or the url directive. Note that if the URL is changed, all applications that connect to the App Engine application will need to change the URL as well. Both methods are detailed below.

Default URL

To map the Remote API to the default path (/remote_api), add the remote_api builtin to your app.yaml file:

- remote_api: on

Custom URL

If you need to map the Remote API to a path other than the default, you can use the url directive in app.yaml:

For Python 2.7:

- url: /remoteapi.*
  script: google.appengine.ext.remote_api.handler.application

An error is returned if there is no authenticated user or if the authenticated user is not an admin of your application, so there is no need to configure any additional security.

Using the Remote API Shell

The Python SDK includes a Remote API shell which allows you to run a shell that has access to App Engine services and your applications datastore.

To use modules defined by your application you will need to run the Remote API shell from your application's directory. From the application directory, execute the command:

$GAE_SDK_ROOT/ -s <your_app_id>

When executing the Remote API shell you can also provide the flag --oauth2. This will allow you to connect using OAuth 2.0 credentials from the gcloud command line tool, which is more secure than typing in your username and password. You can also provide your OAuth 2.0 credentials through other methods which are detailed on the Application Default Credentials page.

From the Remote API shell you can simply import application modules just as you would in a normal App Engine application. An example of accessing the Guestbook applications datastore is below:

>>>> import helloworld
>>> # Fetch the most recent 10 guestbook entries
>>> entries = helloworld.Greeting.all().order("-date").fetch(10)
>>> # Create our own guestbook entry
>>> helloworld.Greeting(content="A greeting").put()

In general, the Remote API shell behaves exactly as if you were accessing the datastore directly. However because the script is running on your local machine, you can access files and resources on your local machine.

Using the Remote API in a Local Client

These instructions show the use of OAuth 2.0. If you have an older application that uses ClientLogin (where you supply username and password), you should migrate the app to use OAuth 2.0 as shown on this page because ClientLogin is being turned off soon. After making the code changes shown on this page, if you use a Custom URL rather than a built-in, you must also remove login:admin from the remote_api handler (- url: /remoteapi.*) in your application's app.yaml file and you must then redeploy your application. Note that the handler still performs admin authentication even without the login:admin entry, so your application continues to be protected.

The Remote API can also be used within local applications. This will allow you to write local applications that use App Engine services and access datastore. It is important to note that using the Remote API will incur quota usage on the application you are accessing.

Before beginning, make sure the App Engine SDK is added to your Python path and Remote API is enabled in your App Engine application. The following example shows the use of OAuth 2.0 credentials to configure the Remote API:

from google.appengine.ext.remote_api import remote_api_stub
from helloworld import helloworld


# Fetch the most recent 10 guestbook entries
entries = helloworld.Greeting.all().order("-date").fetch(10)
# Create our own guestbook entry
helloworld.Greeting(content="A greeting").put()