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 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 in the Cloud Console, and the functionality provided by Cloud Endpoints (such as authentication, logging, monitoring, and setting quotas) will not be available.

To add API management support to your API:

  1. Add the frameworks library to your API project directory so it will be uploaded with the API code upon deployment:

    1. Change directory to your API's main directory.
    2. Make a /lib subdirectory in the API’s main directory:

      mkdir lib
      
    3. Install the library:

      pip install -t lib google-endpoints --ignore-installed
      
  2. From the API’s main directory, generate an OpenAPI document using the framework tools, for example:

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

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

    Ignore the warnings that are displayed.

    You can list multiple classes on the command line. Endpoints will generate 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:

     python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi --hostname your-service.appspot.com --x-google-api-name
    
  3. Deploy the configuration file:

    gcloud endpoints services deploy echov1openapi.json
    

    This first time you deploy echov1openapi.json, a new Cloud Endpoints service is created with the name YOUR_PROJECT_ID.appspot.com.

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

     gcloud endpoints services deploy foov1openapi.json barv1openapi.json
    

    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 echov1openapi.json 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.

  4. 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 project ID, and [YOUR_SERVICE_VERSION] with your service configuration ID from the previous step. (Do not include the square brackets.)

  5. Re-deploy your API:

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

    curl -H "Content-Type: application/json" -X POST -d '{"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"
    }
    
  8. Making some additional requests to your API.

  9. To view your API metrics, open the Cloud Endpoints dashboard for your project:
    Cloud Endpoints

After your API is managed by Cloud Endpoints, when you view logs on the Stackdriver Logging page in the GCP Console, the logs are available in the Produced API section grouped by service name.
View Logs

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine