Getting Started with Endpoints on Compute Engine

This tutorial shows you how to configure, deploy, and send requests to a sample API running on an instance in Google 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 the request to the API.

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

Task List

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 Cloud Platform project. See Before you begin.
  2. Download the sample code. See Getting the sample code.
  3. Configure the openapi.yaml file, which is used to configure Endpoints. See Configuring Endpoints.
  4. Deploy the Endpoints configuration to create a Cloud Endpoints service. See Deploying the Endpoints configuration.
  5. Create a backend to serve the API and deploy the API. See Deploying the API backend.
  6. Send a request to the API via IP address. See Sending a request via IP address.
  7. Configure a DNS record for the sample API. See Configuring DNS for Endpoints.
  8. Send a request to the API via IP address. See Sending a request via FQDN.
  9. Track API activity. See Tracking API activity.
  10. Avoid incurring charges to your Google Cloud Platform account. See Clean up.

Before you begin

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Cloud Platform project.

    Go to the Manage resources page

  3. Enable billing for your project.

    Enable billing

  4. Note the project ID, because you'll need it later.
  5. Install cURL for testing purposes. On Windows, this tutorial uses PowerShell's built in WebRequest support.
  6. Download the Google Cloud SDK.
  7. Update the Cloud SDK and install the Endpoints components.
    gcloud components update
  8. Make sure that Cloud SDK (gcloud) is authorized to access your data and services on Google Cloud Platform:
    gcloud auth login
    A new browser tab opens and you are prompted to choose an account.
  9. Set the default project to your project ID.
    gcloud config set project [YOUR-PROJECT-ID]

    Replace [YOUR-PROJECT-ID] with your project ID. Do not include the square brackets. If you have other Cloud Platform projects, and you want to use gcloud to manage them, see Managing Cloud SDK Configurations.

Getting the sample code

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 -u -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

The sample code includes the OpenAPI configuration file, openapi.yaml, which is based on OpenAPI Specification v2.0.

To configure Endpoints:
  1. In the sample code directory, open the openapi.yaml configuration file.

    Note: The configuration sample displays the lines that need to be edited. To run Cloud Endpoints, the complete configuration file is required.

  2. In the host field, replace the text with the Cloud Endpoints service name, which should be in the following format:
    host: "echo-api.endpoints.[YOUR-PROJECT-ID].cloud.goog"
    

    Replace [YOUR-PROJECT-ID] with your project ID. Do not include the square brackets. For example:

    host: "echo-api.endpoints.example-project.cloud.goog"
    

Note that echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog is the Endpoints service name. It is not the fully qualified domain name (FQDN) that you use for sending requests to the API.

After you have finished all the following configuration steps such that you can successfully send requests to the sample API using an IP address, see Configuring Endpoints DNS for information on how to configure echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog to be the FQDN.

Deploying the Endpoints configuration

To deploy the Endpoints configuration, you use Google Service Management, an infrastructure service of Google Cloud Platform that manages other APIs and services, including services created using Cloud Endpoints.

To deploy the Endpoints configuration:

  1. Make sure you are in the endpoints/getting-started directory.
  2. Invoke the following command:
    gcloud service-management deploy openapi.yaml
    

    Service Management uses the text that you specified in the host field in the openapi.yaml file to create a new Cloud Endpoints service with the name echo-api.endpoints.[YOUR-PROJECT-ID].cloud.goog (if it does not exist), and then configures the service according to your OpenAPI configuration file.

    As it is creating and configuring the service, Service Management outputs a great deal of information to the terminal. You can safely ignore the warnings about the paths in openapi.yaml not requiring an API key. On successful completion, you will see a line like the following that displays the service configuration ID and the service name:

    Service Configuration [2017-02-13-r2] uploaded for service [echo-api.endpoints.example-project.cloud.goog]
    
  3. Display the service configuration ID by running the command:
    gcloud service-management configs list --service=echo-api.endpoints.[PROJECT-ID].cloud.goog
    

    Replace [PROJECT-ID] with your project ID. Do not include the square brackets.

  4. Make a note of the service configuration ID because you'll need it when adding metadata to configure the Compute Engine instance in the next section.

Deploying the API backend

So far you have deployed the OpenAPI configuration to Service Management, but you have not yet deployed the code that will serve the API backend. This section walks you through creating a Compute Engine instance to host the API backend and deploying the API.

Creating a Compute Engine instance

To create a Compute Engine instance to run the sample API server and the required Extensible Service Proxy:

  1. Open the Create VM Instance page in the Google Cloud Platform Console.

    Create VM instance

  2. Check Allow HTTP traffic and Allow HTTPS traffic in the Firewall rules.

  3. Expand the Management, disk, networking, SSH keys section.

  4. In the Metadata section and add the following Endpoints metadata key/value pairs:

    1. Specify endpoints-service-name as a key and echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog as its value, replacing YOUR-PROJECT-ID with your project ID.
    2. Click Add item.
    3. Specify endpoints-service-config-id as a key and the service configuration ID as the key's value.
  5. Leave all other default values as they are.

  6. Click Create to create the instance.
  7. Make a note of the instance name, zone, and external IP address because you'll need them later. It can take a few minutes before the external IP address appears.

Running the sample API

Java
To install and run the sample API on the instance:
  1. Set the zone for your project by invoking the command:
    gcloud config set compute/zone [YOUR-INSTANCE-ZONE]
    
    Replace [YOUR-INSTANCE-ZONE] with the zone where your instance is running. Do not include the square brackets.
  2. In the sample API directory java-docs-samples/endpoints/getting-started, copy the sample API files from your local machine to the Compute Engine instance:
      gcloud compute scp --scp-flag=-pr ../../endpoints [INSTANCE-NAME]:~/
      gcloud compute scp ../../pom.xml [INSTANCE-NAME]:~/
      
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets. You may be prompted to create an SSH key in order to do the copy. If so, follow the prompts to create the key.
  3. Connect to your instance using the following command:
    gcloud compute ssh [INSTANCE-NAME]
    
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets.
  4. Set up a virtual environment in your instance and run the sample API:

    The sample API requires OpenJDK 8 and Maven. Run the following commands to get the correct versions of these packages and install them on your Compute Engine instance:

    sudo apt-get update
    sudo apt-get install openjdk-8-jdk maven
    cd endpoints/getting-started
    mvn -Djetty.http.port=8081 jetty:run
    
  5. The sample API is now running on the instance. However, you need to run the Extensible Service Proxy before sending requests to the API.
Python
To install and run the sample API on the instance:
  1. Set the zone for your project by invoking the command:
    gcloud config set compute/zone [YOUR-INSTANCE-ZONE]
    
    Replace [YOUR-INSTANCE-ZONE] with the zone where your instance is running. Do not include the square brackets.
  2. In the sample API directory python-docs-samples/endpoints/getting-started, copy the sample API files from your local machine to the Compute Engine instance:
      gcloud compute scp --recurse . [INSTANCE-NAME]:~/
      
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets. You may be prompted to create an SSH key in order to do the copy. If so, follow the prompts to create the key.
  3. Connect to your instance using the following command:
    gcloud compute ssh [INSTANCE-NAME]
    
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets.
  4. Set up a virtual environment in your instance and run the sample API:
    sudo easy_install virtualenv
    virtualenv .
    ./bin/pip install -r requirements.txt
    ./bin/gunicorn -b :8081 main:app
    
  5. The sample API is now running on the instance. However, you need to run the Extensible Service Proxy before sending requests to the API.
Go
To install and run the sample API on the instance:
  1. Set the zone for your project by invoking the command:
    gcloud config set compute/zone [YOUR-INSTANCE-ZONE]
    
    Replace [YOUR-INSTANCE-ZONE] with the zone where your instance is running. Do not include the square brackets.
  2. In the sample API directory golang-samples/endpoints/getting-started, copy the sample API files from your local machine to the Compute Engine instance:
      gcloud compute scp --recurse . [INSTANCE-NAME]:~/
      
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets. You may be prompted to create an SSH key in order to do the copy. If so, follow the prompts to create the key.
  3. Connect to your instance using the following command:
    gcloud compute ssh [INSTANCE-NAME]
    
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets.
  4. Set up a virtual environment in your instance and run the sample API:
    sudo apt-get install git -y
    curl https://storage.googleapis.com/golang/go1.7.3.linux-amd64.tar.gz | tar xzf -
    GOPATH=$HOME GOROOT=$HOME/go go/bin/go get ./...
    export PORT=8081
    GOPATH=$HOME GOROOT=$HOME/go go/bin/go run app.go
    
  5. The sample API is now running on the instance. However, you need to run the Extensible Service Proxy before sending requests to the API.
PHP
To install and run the sample API on the instance:
  1. Set the zone for your project by invoking the command:
    gcloud config set compute/zone [YOUR-INSTANCE-ZONE]
    
    Replace [YOUR-INSTANCE-ZONE] with the zone where your instance is running. Do not include the square brackets.
  2. In the sample API directory php-docs-samples/endpoints/getting-started, copy the sample API files from your local machine to the Compute Engine instance:
      gcloud compute scp --recurse . [INSTANCE-NAME]:~/
      
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets. You may be prompted to create an SSH key in order to do the copy. If so, follow the prompts to create the key.
  3. Connect to your instance using the following command:
    gcloud compute ssh [INSTANCE-NAME]
    
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets.
  4. Set up a virtual environment in your instance and run the sample API:
    sudo apt-get install php5-cli
    curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
    composer install
    php -S 127.0.0.1:8081
    
  5. The sample API is now running on the instance. However, you need to run the Extensible Service Proxy before sending requests to the API.
Ruby
To install and run the sample API on the instance:
  1. Set the zone for your project by invoking the command:
    gcloud config set compute/zone [YOUR-INSTANCE-ZONE]
    
    Replace [YOUR-INSTANCE-ZONE] with the zone where your instance is running. Do not include the square brackets.
  2. In the sample API directory ruby-docs-samples/endpoints/getting-started, copy the sample API files from your local machine to the Compute Engine instance:
      gcloud compute scp --recurse . [INSTANCE-NAME]:~/
      
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets. You may be prompted to create an SSH key in order to do the copy. If so, follow the prompts to create the key.
  3. Connect to your instance using the following command:
    gcloud compute ssh [INSTANCE-NAME]
    
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets.
  4. Set up a virtual environment in your instance and run the sample API:
    sudo apt-get install build-essential ruby ruby-dev
    sudo gem install bundler
    bundle install
    bundle exec ruby app.rb -p 8081
    
  5. The sample API is now running on the instance. However, you need to run the Extensible Service Proxy before sending requests to the API.
NodeJS
To install and run the sample API on the instance:
  1. Set the zone for your project by invoking the command:
    gcloud config set compute/zone [YOUR-INSTANCE-ZONE]
    
    Replace [YOUR-INSTANCE-ZONE] with the zone where your instance is running. Do not include the square brackets.
  2. In the sample API directory nodejs-docs-samples/endpoints/getting-started, copy the sample API files from your local machine to the Compute Engine instance:
      gcloud compute scp --recurse . [INSTANCE-NAME]:~/
      
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets. You may be prompted to create an SSH key in order to do the copy. If so, follow the prompts to create the key.
  3. Connect to your instance using the following command:
    gcloud compute ssh [INSTANCE-NAME]
    
    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets.
  4. Set up a virtual environment in your instance and run the sample API:

    Note: If npm is not installed on your instance, it can be installed using the system's package manager. Instructions on installing npm using package managers in popular Linux distributions, FreeBSD and Windows Server can be found on the NodeJS website.

    npm install
    export PORT=8081
    npm start
    
  5. The sample API is now running on the instance. However, you need to run the Extensible Service Proxy before sending requests to the API.

Running the Extensible Service Proxy

The Extensible Service Proxy is an NGINX-based proxy that sits in front of your backend code. It processes incoming traffic to provide auth, API Key management, logging, and other Endpoints API Management features.

To install and run Extensible Service Proxy:

  1. Open a new terminal window, and connect to your instance using the following command:

    gcloud compute ssh [INSTANCE-NAME]
    

    Replace [INSTANCE-NAME] with your instance name. Do not include the square brackets.

  2. Install Google's Endpoints apt repository:

    1. Create an environment variable for the required distribution:

      export CLOUD_ENDPOINTS_REPO="google-cloud-endpoints-jessie"
      
    2. Add the Cloud SDK distribution URI as a package source:

      echo "deb http://packages.cloud.google.com/apt $CLOUD_ENDPOINTS_REPO main" | sudo tee /etc/apt/sources.list.d/google-cloud-endpoints.list
      
    3. Import the Google Cloud public key:

      curl --silent https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
      
    4. Update and install the Cloud SDK:

      sudo apt-get update && sudo apt-get install google-cloud-sdk
      
  3. Install the Extensible Service Proxy from the apt repository:

    sudo apt-get install endpoints-runtime
    
  4. Edit /etc/default/nginx as root to set the listening port to 80, as follows:

    PORT=80
    
  5. Start the Extensible Service Proxy by running the command:

    sudo service nginx restart
    

Sending a request via IP address

Once the sample API and the Extensible Service Proxy are running on the Compute Engine instance, you can send requests to the API.

To send a request to the API:

  1. Create an API key in the API credentials page.

    Create an API key.

    1. Click Create credentials, then select API key.
    2. Copy the key, then paste it into the following environment variable statement:

      • In Linux or Mac OS: export ENDPOINTS_KEY=AIza...
      • In Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."
  2. Send an HTTP request using curl or Invoke-WebRequest:

    • In Linux or Mac OS:
      curl -d '{"message":"hello world"}' -H "content-type:application/json" "http://[IP_ADDRESS]:80/echo?key=${ENDPOINTS_KEY}"
    • In Windows PowerShell:
      (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://[IP_ADDRESS]:80/echo?key=$Env:ENDPOINTS_KEY").Content

    Replace [IP_ADDRESS] with the external IP address of your instance. Do not include the square brackets.

Configuring DNS for Endpoints

Because the Cloud Endpoints service name for the API is in the .endpoints.PROJECT-ID.cloud.goog domain, you can use it as the fully qualified domain name (FQDN) by making a small configuration change in your openapi.yaml file. This way, you can send requests to the sample API using echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog instead of the IP address.

To configure Endpoints DNS:

  1. Open your OpenAPI configuration file, openapi.yaml, and add the x-google-endpoints property at the top level of the file (not indented or nested) as shown in the following snippet:
        host: "echo-api.endpoints.[PROJECT_ID].cloud.goog"
        x-google-endpoints:
        - name: "echo-api.endpoints.[PROJECT_ID].cloud.goog"
          target: "[IP_ADDRESS]"
    
  2. In the name property, replace [PROJECT_ID] with your project ID. Do not include the square brackets.
  3. In the target property, replace [IP_ADDRESS] with the IP address that you used when you sent a request to the sample API. Do not include the square brackets.
  4. Deploy your updated OpenAPI configuration file to Service Management using the following command:
        gcloud service-management deploy openapi.yaml
    

For example, assume openapi.yaml has the following configured:

    host: "echo-api.endpoints.example-project.cloud.goog"
    x-google-endpoints:
    - name: "echo-api.endpoints.example-project.cloud.goog"
      target: "192.0.2.1"

When you deploy the openapi.yaml using the above gcloud command, 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. Note that it could take a few minutes for the new DNS configuration to propagate.

Sending a request via FQDN

Now that you've got the DNS record configured for the sample API, send a request to it using the FQDN (replace [PROJECT_ID] with your project ID):
  • In Linux or Mac OS:
    curl -d '{"message":"hello world"}' -H "content-type:application/json" "http://echo-api.endpoints.[PROJECT_ID].cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • In Windows PowerShell:
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[PROJECT_ID]:80/echo?key=$Env:ENDPOINTS_KEY").Content

You have deployed and tested an API in Cloud Endpoints!

Tracking API activity

To track API activity:

  1. Look at the activity graphs for your API in the Endpoints page.
    View Endpoints activity graphs
    It may take a few moments for the request to be reflected in the graphs.

  2. Look at the request logs for your API in the Logs Viewer page.
    View Endpoints request logs

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this quickstart:

See Deleting an API and API Instances for information on stopping the services used by this tutorial.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Endpoints with OpenAPI