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.
Downloading the sample code
Download the sample code to your local machine.Java
To clone or download the sample API:
Clone the sample app repository to your local machine:
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
Create an instance template
Create a template that you will use to create a group of VM instances. Each
instance created from the template launches an ESPv2 and a backend
application server.
In the Google Cloud console, go to theInstance templatespage.
UnderAutohealingandHealth check, selectNo health check.
ClickCreate. This redirects you back to theInstance groupspage.
Create a load balancer
This section explains the steps required to create a global load
balancer that directs HTTP traffic to your instance group.
This load balancer uses a frontend to receive incoming traffic and a backend to
distribute this traffic to healthy instances. Because the load balancer is
made of multiple components, this task is divided into several parts:
Backend configuration
Frontend configuration
Review and finalize
Complete all the steps to create the load balancer.
In the Google Cloud console, go to theCreate a load balancerpage.
In theApplication Load Balancer (HTTP/S)section, clickStart configuration.
UnderInternet facing or internal only, selectFrom Internet to my VMs. Then, clickContinue.
For theNameof the load balancer, enterespv2-load-balancer.
Backend configuration
In the left panel of theCreate global external Application Load Balancerpage, clickBackend configuration.
ClickCreate or select backend services & backend bucketsto open a
drop-down menu. ClickBackend services, then clickCreate a backend service.
In the new window, for theNameof the backend
application, enterespv2-backend.
SetInstance grouptoload-balancing-espv2-group.
SetPort numbersto80. Thisallows HTTP trafficbetween the load balancer and the instance group.
UnderBalancing mode, selectUtilization.
ClickDoneto create the backend.
Create the health check for the backend of the load balancer:
UnderHealth check, selectCreate a health check(orCreate another health check) from the drop-down menu. A new window
opens.
In the new window underName, enterespv2-load-balancer-check.
Set theProtocoltoHTTP.
UnderPort, enter80.
For this tutorial, set theRequest pathto/healthz, which is a
path that the ESPv2 is set up to respond to.
Set the followingHealth criteria:
SetCheck intervalto3seconds. This defines the amount of
time from the start of one probe to the start of the next one.
SetTimeoutto3seconds. This defines the amount of time
that Google Cloud waits for a response to a probe. Its
value must be less than or equal to the check interval.
SetHealthy Thresholdto2consecutive successes. This
defines the number of sequential probes that must succeed in order
for the instance to be considered healthy.
SetUnhealthy Thresholdto2consecutive failures. This
defines the number of sequential probes that must fail in order
for the instance to be considered unhealthy.
ClickSave and continueto create the health check.
ClickCreateto create the backend service.
Frontend configuration
In the left panel of theCreate global external Application Load Balancerpage, clickFrontend configuration.
On theFrontend configurationpage, underName, enterespv2-ipv4-frontend.
Set theProtocoltoHTTP.
Set thePortto80.
ClickDoneto create the frontend.
Review and finalize
Verify your load balancing settings before creating the load balancer:
In the left panel of theCreate global external Application Load Balancerpage,
clickReview and finalize.
On theReview and finalizepage, verify the followingBackendsettings:
TheBackend serviceisespv2-backend.
TheEndpoint protocolisHTTP.
TheHealth checkisespv2-load-balancer-check.
TheInstance groupisload-balancing-espv2-group.
On the same page, verify thatFrontenduses an IP
address with aProtocolofHTTP.
In the left panel of theCreate global external Application Load Balancerpage, clickCreateto finish creating the load balancer.
You might need to wait a few minutes for the load balancer creation to finish.
After the load balancer is created, find the IP address from theLoad Balancerpage.
After the sample API and ESPv2 are running on the deployed
backend, 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.
Make sure that the gcloud CLI (gcloud) is authorized to access your
data and services on Google Cloud:
gcloud auth login
Enter the following to display the project IDs for your Google Cloud
projects:
gcloud projects list
Using the applicable project ID from the previous step, set the default
Google Cloud project to the one that your application is in:
gcloudconfigsetproject[YOUR_PROJECT_ID]
Obtain the name of all managed services in your Google Cloud project:
gcloud endpoints services list
Delete the service from Service Management. ReplaceSERVICE_NAMEwith the name of the service you want
to remove.
gcloud endpoints services deleteSERVICE_NAME
Runninggcloud endpoints services deletedoesn't immediately delete the
managed service. Service Management disables the managed service for
30 days, which allows you time to restore it if you need to. After 30 days,
Service Management permanently deletes the managed service.
[[["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-03 UTC."],[[["\u003cp\u003eThis tutorial guides users through configuring and deploying a sample REST API using the OpenAPI specification and the Extensible Service Proxy V2 (ESPv2) on Managed Instance Groups (MIGs) within Google Cloud.\u003c/p\u003e\n"],["\u003cp\u003eThe process involves setting up a Google Cloud project, downloading sample code, configuring the \u003ccode\u003eopenapi.yaml\u003c/code\u003e file for Endpoints, deploying the Endpoints configuration and API backend, sending requests to the API using an IP address and later FQDN, and finally tracking API activity.\u003c/p\u003e\n"],["\u003cp\u003eUsers will need to create an API key and set it as an environment variable to send requests to the sample API, and the tutorial also covers how to configure DNS for the API so that it is accessible through a Fully Qualified Domain Name.\u003c/p\u003e\n"],["\u003cp\u003eThe document provides detailed steps on creating instance templates and regional managed instance groups, configuring a global load balancer, and managing required Google Cloud services for the API to function correctly.\u003c/p\u003e\n"],["\u003cp\u003eThe user will be shown how to clean up their resources after going through the tutorial to ensure they do not incur extra charges in their Google Cloud project.\u003c/p\u003e\n"]]],[],null,[]]