Getting started with Cloud Endpoints for Compute Engine with ESPv2

This tutorial shows you how to configure and deploy a sample API and the Extensible Service Proxy V2 (ESPv2) running in prebuilt Docker containers on Compute Engine.

The sample code's REST API is described using the OpenAPI specification. The tutorial also shows you how to create an API key and use it in requests to the API.

For an overview of Cloud Endpoints, see About Endpoints and Endpoints architecture.

Objectives

Use the following high-level task list as you work through the tutorial. All tasks are required to successfully send requests to the API.

  1. Set up a Google Cloud project. See Before you begin.
  2. Create a Compute Engine VM instance. See Creating a Compute Engine instance.
  3. Download the sample code. See Getting the sample code.
  4. Configure the openapi.yaml file, which is used to configure Endpoints. See Configuring Endpoints.
  5. Deploy the Endpoints configuration to create a Endpoints service. See Deploying the Endpoints configuration.
  6. Deploy the API and ESPv2 on the Compute Engine VM. See Deploying the API backend.
  7. Send a request to the API by using an IP address. See Sending a request by using IP address.
  8. Configure a DNS record for the sample API. See Configuring DNS for Endpoints.
  9. Send a request to the API by using the fully qualified domain name. See Sending a request by using FQDN.
  10. Track API activity. See Tracking API activity.
  11. Avoid incurring charges to your Google Cloud account. See Clean up.

Costs

In this document, you use the following billable components of Google Cloud:

To generate a cost estimate based on your projected usage, use the pricing calculator.

New Google Cloud users might be eligible for a free 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, see Clean up.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Make a note of the project ID because it's needed later.

  7. You need an application to send requests to the sample API.

    • Linux and macOS users: This tutorial provides an example of using curl, which typically comes pre-installed on your operating system. If you don't have curl, you can download it from the curl Releases and downloads page.
    • Windows users: This tutorial provides an example using Invoke-WebRequest, which is supported in PowerShell 3.0 and later.
  8. Download the Google Cloud CLI.
  9. Update the gcloud CLI and install the Endpoints components. 
    gcloud components update
  10. 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.
  11. Set the default project to your project ID. 
    gcloud config set project YOUR_PROJECT_ID

    Replace YOUR_PROJECT_ID with your project ID. If you have other Google Cloud projects, and you want to use gcloud to manage them, see Managing 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, see Clean up.

Creating a Compute Engine instance

    To create a Compute Engine instance:

    1. In the Google Cloud console, go to the Create an instance page.

      Go to Create an instance

    2. Click Select.
    3. In the Firewall section, select Allow HTTP traffic and Allow HTTPS traffic.
    4. To create the VM, click Create.

      5. Screenshot of the VM instance creation window with the required options set

      Allow a short time for the instance to start up. Once ready, it is listed on the VM Instances page with a green status icon.

    5. Make sure you that you can connect to your VM instance.
      1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
      2. You can now use the terminal to run Linux commands on your Debian instance.
      3. Enter exit to disconnect from the instance.
    6. Make a note the instance name, zone, and external IP address because they are needed later.

Downloading the sample code

Download the sample code to your local machine.

Java

To clone or download the sample API:

  1. Clone the sample app repository to your local machine: 
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code: 
    cd java-docs-samples/endpoints/getting-started
Python

To clone or download the sample API:

  1. Clone the sample app repository to your local machine: 
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code: 
    cd python-docs-samples/endpoints/getting-started
Go

To clone or download the sample API:

  1. Make sure your GOPATH environment variable is set.
  2. Clone the sample app repository to your local machine: 
    go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. Change to the directory that contains the sample code: 
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

To clone or download the sample API:

  1. Clone the sample app repository to your local machine: 
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code: 
    cd php-docs-samples/endpoints/getting-started
Ruby

To clone or download the sample API:

  1. Clone the sample app repository to your local machine: 
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code: 
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

To clone or download the sample API:

  1. Clone the sample app repository to your local machine: 
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    Alternatively, download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code: 
    cd nodejs-docs-samples/endpoints/getting-started

Configuring Endpoints

You must have an OpenAPI document based on either OpenAPI 2.0 or OpenAPI 3.x that describes the surface of your apps and any authentication requirements. To learn more, see Supported OpenAPI versions.

You also need to add a Google-specific field that contains the URL for each app so that ESPv2 has the information it needs to invoke an app. If you are new to OpenAPI, see OpenAPI overview for more information.

OpenAPI 2.0

To configure Endpoints using an OpenAPI 2.0 specification, you can use the openapi.yaml file available in the endpoints/getting-started directory of the downloaded sample code.

The contents of the OpenAPI 2.0 specification should look similar to the following:

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"

host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"

consumes:
  - "application/json"
produces:
  - "application/json"

schemes:
# Uncomment the next line if you configure SSL for this API.
# - "https"
  - "http"

paths:
  /echo:
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
        - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
        -
          description: "Message to echo"
          in: body
          name: message
          required: true
          schema