Adding API Management

Endpoints Frameworks provides API management features that are comparable to the features that the Extensible Service Proxy (ESP) provides for Cloud Endpoints. Endpoints Frameworks includes a built-in API gateway that intercepts all requests and performs any necessary checks (such as authentication) before forwarding the request to the API backend. When the backend responds, Endpoints Frameworks gathers and reports telemetry. You can view metrics for your API on the Endpoints Services page in the Google Cloud Platform (GCP) Console.

The API management features available in Endpoints Frameworks include:

For your API to be managed by Cloud Endpoints, you must deploy an OpenAPI document that describes your API using version 2.0 of the OpenAPI Specification. This page describes how to generate and deploy an OpenAPI document that enables Cloud Endpoints to manage your API.

If you do not add API management, your API will still serve requests, but your API will not appear on the Endpoints Services page in the GCP Console, and the functionality provided by Cloud Endpoints (such as logging, monitoring, and setting quotas) will not be available.

Installing and configuring required software

If you haven't already done so, install and configure the Cloud SDK for Python, and add the Frameworks Python library to your API project directory so it will be uploaded with the API code upon deployment

Installing and configuring the Cloud SDK for Python

  1. Install and initialize Cloud SDK:

    Download and install Cloud SDK

  2. Run the following command to install the gcloud component that includes the App Engine extension for Python:

    gcloud components install app-engine-python
    
  3. Update the Cloud SDK.

    gcloud components update
    
  4. Make sure that the Cloud SDK is authorized to access your data and services on GCP:

    gcloud auth login
    

    A new browser tab opens and you are prompted to choose an account.

  5. Set the default project to your project ID. Replace [YOUR_PROJECT_ID] with your GCP project ID.

    gcloud config set project [YOUR_PROJECT_ID]
    
  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)"
    

Adding the Frameworks Python library

  1. 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).

  2. Change directory to your API's main directory.

  3. Make a /lib subdirectory in the API’s main directory:

    mkdir lib
    
  4. Install the library:

    pip install -t lib google-endpoints --ignore-installed
    

Generate the OpenAPI document

From the API’s main directory, generate an OpenAPI document using the framework tools. For example:

Single Class

In the following command, replace [YOUR_PROJECT_ID] with your GCP project ID.

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

Ignore the warnings that are displayed.

Multiple Classes

You can list multiple classes on the command line. Cloud Endpoints generates an OpenAPI document for each API name/version combination.

If you want to deploy multiple API classes with different API names as part of a single service, you must also add the --x-google-api-name flag. Enabling this flag adds extra restrictions on your API names. Specifically, the names must match the regular expression [a-z][a-z0-9]{0,39}; that is, the name must consist of 1-40 characters, which may all be either lowercase alphabetical characters or numbers, except that the first character may not be a number. For example:

In the following command, replace [YOUR_PROJECT_ID] with your GCP project ID.

python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \
   --hostname [YOUR_PROJECT_ID].appspot.com \
   --x-google-api-name

Ignore the warnings that are displayed.

Cloud Endpoints uses the text that you specify in the hostname argument as the service name. When you deploy the API to App Engine, a DNS entry with a name in the format YOUR-PROJECT-ID.appspot.com is created automatically.

Deploy the OpenAPI document

Single Class

gcloud endpoints services deploy echov1openapi.json

Multiple Classes

If you have multiple OpenAPI documents, list them all on the command line. For example:

 gcloud endpoints services deploy foov1openapi.json barv1openapi.json

This first time you deploy your OpenAPI document (or documents), a new Cloud Endpoints service is created with the name YOUR_PROJECT_ID.appspot.com.

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-13r0] uploaded for service [example-project-12345.appspot.com]

In the example above, 2017-02-13r0 is the service configuration ID. The service configuration ID consists of a date stamp followed by a revision number. If you deploy your OpenAPI document again, the revision number is incremented in the service configuration ID.

If you need to display the service configuration ID again, run the following command, but replace [YOUR_PROJECT_ID] with the project ID of your Cloud project:

gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com

You can create your own OpenAPI document and deploy it, rather than using a generated one. Simply replace echov1openapi.json above with the path to your OpenAPI document. For more information on writing an OpenAPI document, see OpenAPI Overview.

Re-deploy your API and test

  1. Edit your project's file app.yaml env_variables section as follows:

    env_variables:
      ENDPOINTS_SERVICE_NAME: [YOUR_PROJECT_ID].appspot.com
      ENDPOINTS_SERVICE_VERSION: [YOUR_SERVICE_VERSION]
    

    Replace [YOUR_PROJECT_ID] with your GCP project ID, and [YOUR_SERVICE_VERSION] with your service configuration ID from the previous section. (Do not include the square brackets.) With this addition to app.yaml, Cloud Endpoints will manage your API after you re-deploy your app.

  2. Re-deploy your app:

    gcloud app deploy
    
  3. 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.
    
  4. Test for a successful re-deployment, for example, using curl:

    curl --request POST \
        --header "Content-Type: application/json" \
        --data '{"content":"echo"}' \
        https://[PROJECT-ID].appspot.com/_ah/api/echo/v1/echo?n=2
    

    Replace [PROJECT-ID] with your project ID; replace echo with the name of your API.

    View the results: you should see something like:

    {
     "content": "echo echo"
    }
    
  5. Making some additional requests to your API.

  6. To view your API metrics, open the Endpoints Services page in the GCP Console for your project:
    Endpoints Services Page

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.