Cloud 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 console.
The API management features available in Endpoints Frameworks include:
For your API to be managed by 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 Endpoints to manage your API.
If you don't add API management, your API still serves requests, but your API doesn't appear on the Endpoints > Services page in the Google Cloud console, and the functionality provided by Endpoints, such as logging, monitoring, and setting quotas, isn't available.
Installing and configuring required software
If you haven't already done so, install and configure the Google Cloud CLI for Python, and add the Endpoints Frameworks Python library to your API project directory so it is uploaded with the API code upon deployment
Install and configure the gcloud CLI for Python
Install and initialize gcloud CLI:
Install the
gcloud
component that includes the App Engine extension for Python:gcloud components install app-engine-python
Update the gcloud CLI:
gcloud components update
Make sure that the gcloud CLI is authorized to access your data and services on Google Cloud:
gcloud auth login
A new browser tab opens and you are prompted to choose an account.
Set the default project to your project ID. Replace
YOUR_PROJECT_ID
with your Google Cloud project ID.gcloud config set project YOUR_PROJECT_ID
For Linux, set the
ENDPOINTS_GAE_SDK
environment variable to the path of your App Engine SDK folder:PATH_TO_CLOUD_SDK/platform/google_appengine
Replace
PATH_TO_CLOUD_SDK
with the output of the following command:gcloud info --format="value(installation.sdk_root)"
Add the Endpoints Frameworks Python library
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 calledpython-dev
).
Change directory to your API's main directory.
Make a
/lib
subdirectory in the API’s main directory:mkdir lib
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 by using the framework tools. For example:
Single Class
In the following command, replace YOUR_PROJECT_ID
with
your Google Cloud 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. 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 can all be either lowercase
alphabetical characters or numbers, except that the first character must not
be a number. For example:
In the following command, replace YOUR_PROJECT_ID
with your Google Cloud 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.
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
Endpoints service is created with the name
YOUR_PROJECT_ID.appspot.com
.
On successful completion, a line similar to the following 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 Google 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.
Redeploy your API and test
Edit your project's file
app.yaml
and add anenv_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 Google Cloud project ID, andYOUR_SERVICE_VERSION
with your service configuration ID from the previous section. With this addition to theapp.yaml
file, Endpoints manages your API after you redeploy your application.Redeploy your application:
gcloud app deploy
Wait a few moments for the deployment to succeed, ignoring the warning messages. When the deployment completes, a message similar to the following is displayed:
File upload done. Updating service [default]...done.
Test for a successful redeployment, for example, using curl:
curl --request POST \ --header "Content-Type: application/json" \ --data '{"content":"echo"}' \ https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2
Replace
echo
with the name of your API.The results should display something similar to:
{ "content": "echo echo" }
Make some additional requests to your API.
To view your API metrics, open the Endpoints > Services page in the Google Cloud console for your project: