This tutorial shows you how to configure and deploy a sample
API and theExtensible Service Proxy (ESP)running in prebuiltDockercontainers onCompute Engine. The sample code's REST API is described using
theOpenAPI specification. The
tutorial also shows you how to create anAPI keyand use it in requests to
the API.
To generate a cost estimate based on your projected usage,
use thepricing calculator.
New Google Cloud users might be eligible for afree trial.
When you finish the tasks that are described in this document, you can avoid
continued billing by deleting the resources that you created. For more information, seeClean up.
Before you begin
Sign in to your Google Cloud account. If you're new to
Google Cloud,create an accountto evaluate how our products perform in
real-world scenarios. New customers also get $300 in free credits to
run, test, and deploy workloads.
In the Google Cloud console, on the project selector page,
select or create a Google Cloud project.
Linux and macOS users: This tutorial provides an example of usingcurl, which typically comes pre-installed on your operating system.
If you don't havecurl, you can download it from thecurlReleases and downloads page.
Windows users: This tutorial provides an example usingInvoke-WebRequest, which is
supported in PowerShell 3.0 and later.
Update the gcloud CLI and install the Endpoints
components.
gcloud components update
Make sure that the Google Cloud CLI (gcloud) is authorized to access
your data and services on Google Cloud:
gcloud auth login
In the new browser tab that opens, select an account.
Set the default project to your project ID.
gcloud config set projectYOUR_PROJECT_ID
ReplaceYOUR_PROJECT_IDwith your project ID.
If you have other Google Cloud projects, and you want to usegcloudto manage them, seeManaging gcloud CLI configurations.
When you finish the tasks that are described in this document, you can avoid
continued billing by deleting the resources that you created. For more information, seeClean up.
Creating a Compute Engine instance
To create a Compute Engine instance:
In the Google Cloud console, go to theCreate an instancepage.
Change to the directory that contains the sample code:
cd nodejs-docs-samples/endpoints/getting-started
Configuring Endpoints
The sample code includes the OpenAPI configuration file,openapi.yaml, which
is based onOpenAPI Specification v2.0.
You configure and deployopenapi.yamlon your local machine.
To configure Endpoints:
In the sample code directory, open theopenapi.yamlconfiguration file.
The configuration sample displays the lines near thehostfield, which you need to modify. To deploy theopenapi.yamlfile
to Endpoints, the complete OpenAPI document is required.
The exampleopenapi.yamlfile contains a section for configuring
authentication that isn't needed for this tutorial. You don't need to
configure the lines withYOUR-SERVICE-ACCOUNT-EMAILandYOUR-CLIENT-ID.
OpenAPI is a language-agnostic specification. The sameopenapi.yamlfile is in thegetting-startedsample in each language GitHub
repository for convenience.
In thehostfield, replace the text with the
Endpoints service name, which should be in the following format:
Note thatecho-api.endpoints.YOUR_PROJECT_ID.cloud.googis the Endpoints service name. It isn't the fully qualified
domain name (FQDN) that you use for sending requests to the API.
For information about the fields in the OpenAPI document that
Endpoints requires, seeConfiguring
Endpoints.
After you have finished all the following configuration steps such that you can
successfully send requests to the sample API by using an IP address, seeConfiguring Endpoints DNSfor
information on how to configureecho-api.endpoints.YOUR_PROJECT_ID.cloud.googto be the FQDN.
Make sure you are in theendpoints/getting-starteddirectory.
Upload the configuration and create a managed service:
gcloud endpoints services deploy openapi.yaml
Thegcloudcommand then calls the Service Management
API to create a managed service with the name that you specified in thehostfield of theopenapi.yamlfile.
Service Management configures the service according to the
settings in theopenapi.yamlfile. When you make changes toopenapi.yaml, you must redeploy the file to update the
Endpoints service.
As it is creating and configuring the service, Service Management
outputs information to the terminal. You can safely ignore the warnings about
the paths in theopenapi.yamlfile not requiring an API key.
When it finishes configuring the service, Service Management displays a
message with the service configuration ID and the service name, similar to the
following:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
In the preceding example,2017-02-13r0is the service
configuration ID, andecho-api.endpoints.example-project-12345.cloud.googis the
Endpoints service. The service configuration ID consists of a
date stamp followed by a revision number. If you deploy theopenapi.yamlfile again on the same day, the revision
number is incremented in the service configuration ID. You can view
the Endpoints service configuration on theEndpoints>Servicespage in the Google Cloud console.
At a minimum, Endpoints and ESP require the
following Google services to be enabled:
Name
Title
servicemanagement.googleapis.com
Service Management API
servicecontrol.googleapis.com
Service Control API
In most cases, thegcloud endpoints services deploycommand enables these
required services. However, thegcloudcommand 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:
To determine theENDPOINTS_SERVICE_NAMEyou can either:
After deploying the Endpoints configuration, go to theEndpointspage in the Cloud console. The list of possibleENDPOINTS_SERVICE_NAMEare shown under theService namecolumn.
For OpenAPI, theENDPOINTS_SERVICE_NAMEis what you specified in thehostfield of your OpenAPI spec. For gRPC, theENDPOINTS_SERVICE_NAMEis what you specified in thenamefield of your gRPC Endpoints configuration.
For more information about thegcloudcommands, seegcloudservices.
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 getting Docker set up on your VM instance and running the API
backend code and theESPin a Docker container.
Checking required permissions
In the Google Cloud console, go to the Compute Engine instances page.
Set the zone for your project by running the command:
gcloud config set compute/zoneYOUR_INSTANCE_ZONE
ReplaceYOUR_INSTANCE_ZONEwith the zone where your instance
is running.
Connect to your instance by using the following command:
gcloud compute sshINSTANCE_NAME
ReplaceINSTANCE_NAMEwith your VM instance name.
See theDocker documentationto set up the Docker repository. Make sure to follow the steps that match the version and architecture of your VM instance:
Jessie or newer
x86_64 / amd64
Run the API and ESP in a Docker container
The ESP is annginx-based proxy that sits in front of
your backend code. It processes incoming traffic to provide authentication, API
key management, logging, and other Endpoints API management
features.
To install and run the sample API and ESP in a Docker container:
Run the sample Echo server that serves the sample API:Java
sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-java:1.0
Python
sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-python:1.0
Go
sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-go:1.0
PHP
sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-php:1.0
Ruby
sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-ruby:1.0
NodeJS
sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-node:1.0
Run the pre-packaged public ESP Docker container.
In the ESP startup options, replaceSERVICE_NAMEwith the name of your service. This is
the same name that you configured in thehostfield of your
OpenAPI document.
The--rollout_strategy=managedoption
configures ESP to use the latest deployed service configuration. When you
specify this option, up to 5 minutes after you deploy a new service
configuration, ESP detects the change and automatically begins using it. We
recommend that you specify this option instead of a specific configuration ID
for ESP to use.
For information about the other ESP options used above, seeESP startup options.
After the sample API and the ESP are running on the
Compute Engine instance, you can send requests to the API from your
local machine.
Create an API key and set an environment variable
The sample code requires an API key. To simplify the request, you set an
environment variable for the API key.
In the same Google Cloud project that you used for your API, create an API key on the
API credentials page. If you want to create an API key in a different Google Cloud project,
seeEnabling an API in your Google Cloud project.
On your local computer, paste the API key to assign it to an environment
variable:
In Linux or macOS:export ENDPOINTS_KEY=AIza...
In Windows PowerShell:$Env:ENDPOINTS_KEY="AIza..."
Send the request
Linux or mac OS
Usecurlto send an HTTP request by using theENDPOINTS_KEYenvironment
variable you set previously. ReplaceIP_ADDRESSwith
the external IP address of your instance.
The--dataoption specifies the data to post to the API.
The--headeroption specifies that the data is in JSON format.
PowerShell
UseInvoke-WebRequestto send an HTTP request by using theENDPOINTS_KEYenvironment variable you set previously. ReplaceIP_ADDRESSwith the external IP address of your
instance.
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, seeInvoke-WebRequestin the Microsoft
documentation.
Third-party app
You can use a third-party application such as the Chrome browser
extensionPostmanto send the
request:
SelectPOSTas the HTTP verb.
For the header, select the keycontent-typeand the valueapplication/json.
For the body, enter the following: {"message":"hello world"}
In the URL, use the actual API key rather than the environment variable.
For example: http://192.0.2.0:80/echo?key=AIza...
The API echoes back the message that you send, and responds with the
following:
Because the Endpoints service name for the API is in the.endpoints.YOUR_PROJECT_ID.cloud.googdomain, you can
use it as the fully qualified domain name (FQDN) by making a small
configuration change in youropenapi.yamlfile. This way, you can
send requests to the sample API by usingecho-api.endpoints.YOUR_PROJECT_ID.cloud.googinstead of the IP address.
To configure Endpoints DNS:
Open your OpenAPI configuration file,openapi.yaml, and add thex-google-endpointsproperty at the top level of the file
(not indented or nested) as shown in the following snippet:
When you deploy theopenapi.yamlfile by using the precedinggcloudcommand, Service Management creates a DNS A-record,echo-api.endpoints.my-project-id.cloud.goog, which resolves to the
target IP address,192.0.2.1. It might take a few minutes for the
new DNS configuration to propagate.
Now that you have the DNS record configured for the sample API, send a
request to it by using the FQDN (replaceYOUR_PROJECT_IDwith your project ID) and theENDPOINTS_KEYenvironment variable set
previously:
To avoid incurring charges to your Google Cloud account for the resources used in this
tutorial, either delete the project that contains the resources, or keep the project and
delete the individual resources.
Delete the API:
gcloud endpoints services deleteSERVICE_NAME
ReplaceSERVICE_NAMEwith the name of your service.
In the Google Cloud console, go to theVM instancespage.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis tutorial guides users through configuring and deploying a sample REST API using OpenAPI specification and the Extensible Service Proxy (ESP) on Google Cloud Compute Engine.\u003c/p\u003e\n"],["\u003cp\u003eThe process involves setting up a Google Cloud project, creating a Compute Engine VM instance, downloading sample code, configuring the \u003ccode\u003eopenapi.yaml\u003c/code\u003e file, and deploying the configuration and API backend.\u003c/p\u003e\n"],["\u003cp\u003eUsers will learn how to generate and utilize an API key for requests, send requests using both IP addresses and fully qualified domain names (FQDN), and configure DNS settings for the API.\u003c/p\u003e\n"],["\u003cp\u003eThe tutorial also covers how to track API activity, clean up resources to avoid continued billing, and has instructions for various languages such as Java, Python, Go, PHP, Ruby, and NodeJS.\u003c/p\u003e\n"],["\u003cp\u003eThis tutorial has a comprehensive look on how to manage the service using the Google Cloud CLI, including deploying, enabling the required services, and managing the service account permissions.\u003c/p\u003e\n"]]],[],null,[]]
