Getting Started with Cloud Endpoints Frameworks on App Engine

This page shows you how to configure, deploy, and send requests to a sample API running on Google App Engine standard using the Google Cloud Endpoints Frameworks for App Engine in Python 2.7.x. Cloud Endpoints Frameworks consists of tools, libraries and capabilities that allow you to generate APIs and client libraries from an App Engine application.

Task list

Use the following high-level task list as you work through the tutorial. All tasks are required to successfully send requests to the API.

  1. Set up a Cloud Platform project and install required software. See Before you begin.
  2. Download the sample code. See Getting the sample code.
  3. Generate an OpenAPI configuration file. See Configuring Endpoints.
  4. Deploy the Endpoints configuration to create a Cloud Endpoints service. See Deploying the Endpoints configuration.
  5. Create a backend to serve the API and deploy the API. See Deploying the API backend.
  6. Send a request to the API. See Sending a request to the API.
  7. Track API activity. See Tracking API activity.
  8. Avoid incurring charges to your Google Cloud Platform account. See Clean up.

Before you begin

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Cloud Platform project.

    Go to the Manage resources page

  3. The Dashboard opens if an App Engine application already exists in your project. Otherwise, you are prompted to choose the region where you want your App Engine application located.

    Note: This application should be run in a B4_1G instance class for improved performance.

  4. Note the project ID, because you'll need it later.
  5. Make sure you have Python 2.7.x installed. Python 3.x is not supported.
  6. Download the Google Cloud SDK.
  7. Update the Cloud SDK and install the Endpoints components:
    gcloud components update
  8. Make sure that Cloud SDK (gcloud) is authorized to access your data and services on Google Cloud Platform:
    gcloud auth login
    A new browser tab opens and you are prompted to choose an account.
  9. Set the default project to your project ID:
    gcloud config set project [YOUR-PROJECT-ID]

    Replace [YOUR-PROJECT-ID] with your project ID. Do not include the square brackets. If you have other Cloud Platform projects, and you want to use gcloud to manage them, see Managing Cloud SDK Configurations.

  10. Install the SDK for App Engine:
    gcloud components install app-engine-python
    

Getting the sample code

To clone the sample API from GitHub:

  1. Clone the sample repository to your local machine:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. Change to the directory containing the sample code:

    cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    

Configuring Endpoints

To configure Endpoints, you first have to install the Cloud Endpoints Frameworks library. You then use a tool from the Frameworks library to generate an OpenAPI configuration file for the sample API.

Installing the Endpoints Frameworks library

This section walks you through using Python's pip to add the Endpoints Frameworks library to the sample API's project directory.

To add the Frameworks library to the sample:

  1. Make sure you are in the sample API's main directory, /python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

  2. Make a /lib subdirectory in the project:

    mkdir lib
    
  3. From the sample main directory /python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo, invoke the following install command:

    pip install -t lib -r requirements.txt --ignore-installed
    

    Notice that the lib directory is vendored in the file /python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo/appengine_config.py

Generating the OpenAPI configuration file

You use a tool from the Frameworks library to generate an OpenAPI configuration file that describes the sample code's REST API.

To generate the OpenAPI configuration file:

  1. Make sure you are in the sample main directory:

    /python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Invoke the Endpoints tool to generate the OpenAPI configuration file:

    python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [PROJECT-ID].appspot.com
    

    Replace [PROJECT-ID] with your Cloud project ID. Do not include the square brackets. Ignore the warnings that are displayed. The Endpoints tool generates an OpenAPI configuration file called echov1openapi.json in the current directory.

    Cloud Endpoints uses the text specified in the hostname argument as the service name. The PROJECT-ID.appspot.com name format matches the DNS entry that is created automatically when you deploy the API to the App Engine backend. So in this case, both the Cloud Endpoints service name and fully qualified domain name (FQDN) are the same.

Deploying the Endpoints configuration

To deploy the Endpoints configuration, you use Google Service Management, an infrastructure service of Google Cloud Platform that manages other APIs and services, including services created using Cloud Endpoints.

To deploy the configuration file:

  1. Make sure you are in the sample main directory:
    /python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Deploy the OpenAPI configuration file that was generated in the previous section by invoking the following command:
    gcloud service-management deploy echov1openapi.json
    

    This creates a new Cloud Endpoints service with the name that you specified in the hostname argument when you ran the Endpoints Frameworks tool to generate the OpenAPI configuration file. No matter what the Endpoints service name is, when you deploy the API on App Enginge, a DNS record is created using the name format PROJECT-ID.appspot.com, which is the FQDN that you use when you send requests to the API.

    As it is creating and configuring the service, Service Management outputs a great deal of information to the terminal. You can safely ignore the warnings about the paths in echov1openapi.json not requiring an API key. On successful completion, you will see a line like the following that displays the service configuration ID and the service name:

    Service Configuration [2017-02-13r2] uploaded for service [example-project.appspot.com]
    

Deploying the API backend

So far you have deployed the OpenAPI configuration to Service Management, but you have not yet deployed the code that will serve the API backend. This section walks you through deploying the sample API to App Engine.

To deploy the API backend:

  1. Display the service configuration ID by running the following command:
    gcloud service-management configs list --service=[PROJECT-ID].appspot.com
    

    Replace [PROJECT-ID] with your project ID. Do not include the square brackets. For example:

    gcloud service-management configs list --service=example-project.appspot.com
    

  2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.
    env_variables:
      # The following values are to be replaced by information from the output of
      # 'gcloud service-management deploy swagger.json' command.
      ENDPOINTS_SERVICE_NAME: [YOUR-PROJECT-ID].appspot.com
      ENDPOINTS_SERVICE_VERSION: 2016-08-01r0
  3. Make the following changes in the env_variables section:
    • In the ENDPOINTS_SERVICE_NAME field, replace [YOUR-PROJECT-ID] with the project ID for your Cloud project. Do not include the square brackets.
    • In the ENDPOINTS_SERVICE_VERSION field, replace the text with the configuration ID from the previous step. For example:
    env_variables:
      # The following values are to be replaced by information from the output of
      # 'gcloud service-management deploy swagger.json' command.
      ENDPOINTS_SERVICE_NAME: example-project.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
    
  4. Invoke the command:
    gcloud app deploy
    
  5. Follow the on-screen prompts. Wait a few moments for the deployment to succeed, ignoring the warning messages. When the deployment completes, you'll see a message similar to the following:
    File upload done.
    Updating service [default]...done.
    

Sending a request to the sample API

After you deploy the API and its configuration file, you can send requests to the API.

To send a request to the API:

  1. Run the following curl command:

    curl -H "Content-Type: application/json" -X POST -d '{"content":"hello world"}' https://[PROJECT-ID].appspot.com/_ah/api/echo/v1/echo
    

    If you are on Windows, instead invoke the following PowerShell cmdlet:

    (Invoke-WebRequest -Method POST -Body '{"content": "hello world"}' -Headers @{"content-type"="application/json"} -URI "https://[PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
    

    Replace [PROJECT-ID] with your project ID. Do not include the square brackets.

  2. The API echos back the message that you send it, and responds with the following:

    {
     "content": "hello world"
    }
    

Note: App Engine may take a few minutes to respond successfully to requests. If you send a request and get back an HTTP 502, 503, or some other server error, wait a minute and try the request again.

You just deployed and tested an API in Cloud Endpoints using the Cloud Endpoints Frameworks!

Tracking API activity

  1. View the activity graphs for your API in the Endpoints page.
    View Endpoints activity graphs
    It may take a few moments for the request to be reflected in the graphs.
  2. Look at the request logs for your API in the Logs Viewer page.
    View Endpoints request logs

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this quickstart:

  1. Go to the Cloud Platform Console to shut down your Cloud Platform project:

    Go to the Projects page

  2. Select the Cloud Platform project that you used to run this Cloud Endpoints tutorial and then click Delete.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Endpoints Frameworks for App Engine