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. See Before you begin.
  2. Install required software and create an App Engine app. See Installing and configuring required software.
  3. Download the sample code. See Getting the sample code.
  4. Generate an OpenAPI document. See Configuring Endpoints.
  5. Deploy the Endpoints configuration to create a Cloud Endpoints service. See Deploying the Endpoints configuration.
  6. Run the sample on your computer. See Running the sample locally.
  7. Create a backend to serve the API and deploy the API. See Deploying the API backend.
  8. Send a request to the API. See Sending a request to the API.
  9. Track API activity. See Tracking API activity.
  10. 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 GCP project.

    Go to the Manage resources page

  3. Make sure that billing is enabled for your project.

    Learn how to enable billing

  4. Note the project ID, because you'll need it later.

Installing and configuring required software

  1. Follow the instructions in Installing Cloud SDK for Python to get your App Engine standard development environment setup. Make sure you install the app-engine-python and app-engine-python-extras gcloud components.
  2. Run the following commands:
    1. Update the Cloud SDK.
      gcloud components update
    2. 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.
    3. Set the default project to your project ID.
      gcloud config set project [YOUR_PROJECT_ID]

      Replace [YOUR_PROJECT_ID] with your Cloud project ID. If you have other Cloud Platform projects, and you want to use gcloud to manage them, see Managing Cloud SDK Configurations.

  3. You will need an application to send requests to the sample API.

    • Linux and Mac users: This tutorial provides an example using curl, which typically comes pre-installed on your operating system. If you don't have curl, you can download it from the curl Releases and Downloads page.
    • Windows users: This tutorial provides an example using Invoke-WebRequest, which is supported in PowerShell 3.0 and later.
  4. Make sure your python development environment includes pip.
  5. Be sure you can compile C extensions for Python.
    • Windows: Microsoft Visual C++ 9.0 or greater is required. You can download the Microsoft Visual C++ Compiler for Python 2.7 from the Microsoft Download Center .
    • Other operating systems: Depending on your operating system, you may need to install compiler tools (sometimes in a package called build-essential) and/or the Python development headers (sometimes in a package called python-dev).
  6. For Linux, set the ENDPOINTS_GAE_SDK environment variable to the path of your App Engine SDK folder: [Path-to-Google-Cloud-SDK]/platform/google_appengine.

    Replace [Path-to-Google-Cloud-SDK] with the output of the following command:

    gcloud info --format="value(installation.sdk_root)"

  7. Create an App Engine app:
    1. Select the region where you want to create your App Engine app. Run the following command to get a list of regions:
      gcloud app regions list
    2. Create an App Engine app using the following command. Replace [YOUR_PROJECT_ID] with your Cloud project ID and [YOUR_REGION] with the region that you want the App Engine app created in.
      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]

      For example:

      gcloud app create --project=example-project-12345 --region=us-central

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 document for the sample API. You need the Endpoints Frameworks library and the OpenAPI document so that Cloud Endpoints can manage the API. For more information see Adding API Management.

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 install command:

    pip install --target lib --requirement requirements.txt --ignore-installed
    

    Note the following:

    • This pip command may use GCC (the GNU Compiler Collection) to compile extension modules. If you are on macOS and this is the first time you have run GCC on your system, you may have to accept Apple's XCode license. To do so, run sudo xcodebuild -license.

    • If you have multiple Python versions installed on your computer, make sure you are using a version of pip corresponding to the Python version you will be using in this tutorial. Version mismatches (pip from Python 3.4 while using python from Python 2.7, for example) can cause errors which can be difficult to understand. If need be, you can run pip as a Python module: replace the pip in the above command with python -m pip.

    • If pip is unable to find a suitable package when running the command, try upgrading it by running pip install --upgrade pip. After the upgrade is complete, try the installation command again.

On successful completion, the lib directory is populated with the libraries required to build the Endpoints Frameworks application.

Generating the OpenAPI document

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

To generate the OpenAPI document:

  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 document:

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

    Replace [YOUR_PROJECT_ID] with your Cloud project ID. Ignore the warnings that are displayed. The Endpoints tool generates an OpenAPI document with the name called echov1openapi.json in the current directory. The Endpoints tool names the file based on the name and version of the service specified in the @endpoints.api decorator. See Creating the API for more information.

    Cloud Endpoints uses the text specified in the hostname argument as the service name. The YOUR_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.

On successful completion, the following message is displayed:

OpenAPI spec written to ./echov1openapi.json

Deploying the Endpoints configuration

To deploy the Endpoints configuration, you use Service Infrastructure, Google’s foundational services platform, used by Endpoints Frameworks and other services to create and manage APIs and services.

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 document that was generated in the previous section by invoking the following command:
    gcloud endpoints services 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 document. 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 YOUR_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-12345.appspot.com]
    

    In the above example, 2017-02-13-r2 is the service configuration ID and example-project-12345.appspot.com is the service name.

    See gcloud endpoints services deploy in the Cloud SDK Reference documentation for more information.

Running the sample locally

After deploying the Endpoints configuration, you can run the sample locally using the Local Development Server.

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

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. To start the local development server, run the command:

    dev_appserver.py ./app.yaml
    

    By default, the development server listens on http://localhost:8080, as indicated in the console logs printed by dev_appserver.py:

    INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
    
  3. Send a request to the local development server:

Linux or Mac OS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"content": "hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

In the above curl:

  • The --data option specifies the data to post to the API.
  • The --header option specifies that the data is in JSON format.

PowerShell

(Invoke-WebRequest -Method POST -Body '{"content": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

In the above example, the first two lines end in a backtick. When you paste the example into PowerShell, make sure there isn't a space following the backticks. For information about the options used in the example request, see Invoke-WebRequest in the Microsoft documentation.

The API echoes back the message that you send it, and responds with the following:

{
 "content": "hello world"
}

Deploying the API backend

So far you have deployed the OpenAPI document 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 endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
    

    Replace [YOUR_PROJECT_ID] with your project ID. For example:

    gcloud endpoints configs list --service=example-project-12345.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 endpoints services 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.
    • In the ENDPOINTS_SERVICE_VERSION field, replace the text with the service configuration ID. For example:
      ENDPOINTS_SERVICE_NAME: example-project-12345.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.
    

    If you got an error message, see the Troubleshooting section in the App Engine documentation for information.

    We recommend that you wait a few minutes before sending requests to your API while App Engine completely initializes.

Sending a request to the sample API

Linux or Mac OS

Send an HTTP request using curl. Replace [YOUR_PROJECT_ID] with your GCP project ID:

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"content":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

In the above curl:

  • The --data option specifies the data to post to the API.
  • The --header option specifies that the data is in JSON format.

PowerShell

Send an HTTP request using Invoke-WebRequest. Replace [YOUR_PROJECT_ID] with your GCP project ID:

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

In the above example, the first two lines end in a backtick. When you paste the example into PowerShell, make sure there isn't a space following the backticks. For information about the options used in the example request, see Invoke-WebRequest in the Microsoft documentation.

Third-party App

You can use a third-party application such as the Chrome browser extension Postman (offered by www.getpostman.com) to send the request:

  • Select POST as the HTTP verb.
  • For the header, select the key content-type and the value application/json.
  • For the body, enter the following:
    {"content":"hello world"}
  • Enter the URL to the sample application. For example:
    https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

The API echoes back the message that you send it, and responds with the following:

{
 "content": "hello world"
}

If you did not get a successful response, see Troubleshooting Response Errors.

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

Creating a developer portal for the API

You can use Cloud Endpoints Portal to create a developer portal, a website that you can use to interact with the sample API. To learn more, see Cloud Endpoints Portal Overview.

Clean up

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

  1. Go to the GCP Console to shut down your GCP project:

    Go to the Projects page

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

What's next

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.