Getting started with Cloud Endpoints Frameworks for Python

This page shows you how to configure, deploy, and send requests to a sample API by using Cloud Endpoints Frameworks for Python. Endpoints Frameworks for Python is integrated with the App Engine standard Python 2.7 runtime environment. Endpoints Frameworks consists of tools, libraries, and capabilities that let you generate APIs and client libraries from an App Engine application.

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 Endpoints Frameworks Python library. You then use a tool from the Endpoints Frameworks library to generate an OpenAPI document for the sample API. You need the Endpoints Frameworks library and the OpenAPI document so that 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.

Note: Don't run Python in a virtual environment. The Endpoints Frameworks packages must be installed in the lib subdirectory under the project directory on your computer.

To add the Endpoints 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, run the install command:

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

   Note the following:

   • This pip command may use GNU Compiler Collection (GCC) 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 are 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 preceding 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 some Debian and Ubuntu releases pip might fail with DistutilsOptionError. If you see this error, add --system flag.

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

Generating the OpenAPI document

You use a tool from the Endpoints Frameworks library to generate a 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. 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 Google Cloud project ID. Ignore the warnings that are displayed. The Endpoints tool generates an OpenAPI document 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.

   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 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 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 running the following command:

   gcloud endpoints services deploy echov1openapi.json

   This creates a new Endpoints service with the name that you specified in the hostname argument when you ran the Endpoints tool to generate the OpenAPI document. No matter what the Endpoints service name is, when you deploy the API on App Engine, 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. When the deployment completes, a message similar to the following displays:

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

   In the preceding 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 gcloud reference documentation for more information.

Checking required services

To provide API management, Endpoints Frameworks requires the following services:

Name	Title
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API

In most cases, the gcloud endpoints services deploy command enables these required services. However, the gcloud command completes successfully but doesn't enable the required services in the following circumstances:

• If you used a third-party application such as Terraform, and you don't include these services.

• You deployed the Endpoints configuration to an existing Google Cloud project in which these services were explicitly disabled.

Use the following command to confirm that the required services are enabled:

gcloud services list

If you do not see the required services listed, enable them:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Also enable your Endpoints service:

gcloud services enable ENDPOINTS_SERVICE_NAME

To determine the ENDPOINTS_SERVICE_NAME you can either:

• After deploying the Endpoints configuration, go to the Endpoints page in the Cloud console. The list of possible ENDPOINTS_SERVICE_NAME are shown under the Service name column.

• For OpenAPI, the ENDPOINTS_SERVICE_NAME is what you specified in the host field of your OpenAPI spec. For gRPC, the ENDPOINTS_SERVICE_NAME is what you specified in the name field of your gRPC Endpoints configuration.

For more information about the gcloud commands, see gcloud services.

Running the sample locally

After deploying the Endpoints configuration, you can run the sample locally by 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. Start the local development server:

   dev_appserver.py ./app.yaml
   

   By default, the development server listens on http://localhost:8080, as indicated in the Google Cloud 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 '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

In the preceding 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 '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

In the previous 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:

{
 "message": "hello world"
}

Deploying the API backend

So far you have deployed the OpenAPI document to Service Management, but you haven't yet deployed the code that serves 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 your Google Cloud project ID.
   • 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. Run the following 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, a message similar to the following displays:

   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 by using curl. Replace [YOUR_PROJECT_ID] with your Google Cloud project ID:

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

In the preceding 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 by using Invoke-WebRequest. Replace [YOUR_PROJECT_ID] with your Google Cloud project ID:

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

In the previous 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 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:
  {"message":"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:

{
 "message": "hello world"
}

If you didn't get a successful response, see Troubleshooting response errors.

Note: If you want to let us know what you liked about this tutorial, feel free to provide feedback at the bottom of this page. Your feedback helps us improve these tutorials.
If you got an error, join the google-cloud-endpoints Google group and let us know what went wrong. This group receives responses from other Endpoints users and from Google engineers, who monitor the group.

Tracking API activity

1. View the activity graphs for your API in the Google Cloud console on the Endpoints > Service page.

   Go to the Endpoints Services page

   It might 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 Explorer page.

   Go to the Logs Explorer page