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 theESPv2in 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 ESPv2 in a Docker container
The ESPv2 is anEnvoy-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 ESPv2 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 ESPv2 Docker container.
In the ESPv2 startup options, replaceSERVICE_NAMEwith the name of your service. This is
the same name that you configured in thehostfield of yourOpenAPI document.
The--rollout_strategy=managedoption
configures ESPv2 to use the latest deployed service configuration. When you
specify this option, within a minute after you deploy a new service
configuration, ESPv2 detects the change and automatically begins using it. We
recommend that you specify this option instead of providing a specific configuration ID
for ESPv2 to use.
For information about the other ESPv2 options used above, seeESPv2 startup options.
After the sample API and the ESPv2 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 you through configuring and deploying a sample REST API and Extensible Service Proxy V2 (ESPv2) using prebuilt Docker containers on 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 both the Endpoints configuration and the API backend.\u003c/p\u003e\n"],["\u003cp\u003eYou will learn how to send requests to the API using its IP address, create and use an API key, configure a DNS record for the API, and then send requests via the fully qualified domain name (FQDN).\u003c/p\u003e\n"],["\u003cp\u003eThe tutorial covers how to use the \u003ccode\u003egcloud\u003c/code\u003e command-line tool to deploy and manage Endpoints services and includes instructions for installing and running Docker containers on the Compute Engine instance.\u003c/p\u003e\n"],["\u003cp\u003eFinally, it provides instructions on how to monitor API activity, such as viewing activity graphs and request logs, and also includes directions on cleaning up resources to avoid incurring further costs.\u003c/p\u003e\n"]]],[],null,[]]
