Getting Started with Endpoints on Container Engine

This tutorial shows you how to configure, deploy, and send requests to a sample API running on an instance in Google Container 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. Install and configure software used in the tutorial. See Installing and configuring required software.
  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 sample API to create a Cloud Endpoints service. See Deploying the sample API.
  6. Create a container cluster for the service. See Creating a container cluster.
  7. Deploy the containers to the cluster. See Deploying the containers to the cluster.
  8. Get the cluster's IP address. See Getting the cluster's external IP address.
  9. Send a request to the API. See Sending a request to the sample API.
  10. Track API activity. See Tracking API activity.
  11. 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 Projects page

  3. Enable billing for your project.

    Enable billing

  4. Note the project ID, because you'll need it later.

Installing and configuring required software

In this tutorial, you'll install the Google Cloud SDK so that you can use the gcloud command line interface to manage your project. You will use kubectl, a command line interface for running commands against Kubernetes clusters. You will also need a way to test the API. This tutorial uses cURL, but you could use an application such as Postman for Google Chrome. On Windows, this tutorial uses PowerShell's built in WebRequest support.

In the following procedure, if you already have the required software installed, continue with the next step.

To install and configure required software

  1. Install cURL for testing purposes. On Windows, this tutorial uses PowerShell's built in WebRequest support.
  2. Install and initialize the Cloud SDK.
  3. Update the Cloud SDK and install the Endpoints components:
    gcloud components update
  4. Make sure that Cloud SDK (gcloud) is authorized to access your data and services on Google Cloud Platform:
    gcloud auth login
    A new brower tab opens and you are prompted to choose an account.
  5. 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.

  6. Install kubectl:
    gcloud components install kubectl
  7. Acquire new user credentials to use for Application Default Credentials. The user credentials are needed to authorize kubectl.
    gcloud auth application-default login
    A new browser tab opens and you are prompted to choose an account.

Getting the sample code

To help you get up and running quickly, sample code is provided in several languages.

To get 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. Clone the sample app repository to your local machine:
    go get -u -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  2. 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 endpoints/getting-started directory, open the openapi.yaml configuration file.
  2. In the host property, replace the text YOUR-PROJECT-ID with your project ID.

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

Deploying the sample API

To deploy the API, 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 sample API

  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 property 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 [2016-12-14r1] uploaded for service [echo-api.endpoints.example-project.cloud.goog]

Creating a container cluster

Now that the service has been created, you need a backend for it to run on. In this tutorial, you create a Container Engine cluster to host the service.

To create a container cluster for the sample API

  1. Visit the Container clusters page.
    Create a Container cluster

  2. Click Create a container cluster.

  3. Accept the defaults and click Create (this step can take a few minutes to complete).

  4. Note the cluster name and zone; you'll need them when you authenticate kubectl to the container cluster.

Deploying the containers to the cluster

Containers offer a logical packaging mechanism in which applications can be abstracted from the environment in which they actually run. You use the following procedure to deploy the container-based sample application to the cluster.

To deploy to the containers to the cluster

  1. Get cluster credentials and make them available to kubectl:
    gcloud container clusters get-credentials [NAME] --zone [ZONE]
    Replace [NAME] with the cluster name and [ZONE] with the cluster zone. Do not include the square brackets.

  2. Get the service configuration ID by invoking the command:
    gcloud service-management configs list --service=echo-api.endpoints.[YOUR-PROJECT-ID].cloud.goog

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

    gcloud service-management configs list --service=echo-api.endpoints.example-project.cloud.goog
  3. Edit the Kubernetes configuration file /endpoints/getting-started/container-engine.yaml, and replace SERVICE_NAME and SERVICE_CONFIG_ID shown in the snippet below with the values returned from the command in the previous step.

    For example:

      args: [
        "-p", "8081",
        "-a", "127.0.0.1:8080",
        "-s", "echo-api.endpoints.example-project.cloud.goog ",
        "-v", "2016-12-14r1",
      ]
    
  4. Start the service using the kubectl create command:
    kubectl create -f container-engine.yaml

Getting the cluster's external IP address

To send requests to the API, you need the external IP of the service. It can take a few minutes after you start your service in the container before the external IP address is ready.

To view the external IP address

  1. Invoke the command:

    kubectl get service
    
  2. Note the value for EXTERNAL-IP. You'll use that IP address when you send a request to the sample API.

Sending a request to the sample API

Now that the service is running in the container cluster, and you have the external IP address, 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 to the clipboard.
    3. Click Restrict key.
    4. On the Credentials page, click Save.
  2. Create an environment variable called ENDPOINTS_KEY for the API key:

    • Linux or Mac OS: export ENDPOINTS_KEY=AIza...
    • Windows Powershell: $Env:ENDPOINTS_KEY="AIza...
  3. 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. The API echos back the message that you send it, and responds with the following:

{
  "message": "hello world"
}

In the above curl:

  • The -d option specifies the data to post to the API.
  • The -H option specifies the header.
  • The query parameter key is set to the API key. The example uses the environment variable ${ENDPOINTS_KEY}. If you prefer, you can copy/paste the API key as the value for the key query parameter. In that case, don't surround it with ${}.

If you would prefer to use an application such as Postman to send the request, you would configure it as follows:

  • Select POST as the HTTP verb.
  • For the header, select the key content-type and the value application/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=AIzaSyBmDH4jBQhbR7yxKJ9IAq-Dmlio5Wh3rD0

Tracking API activity

Cloud Platform provides several ways to track 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

You just deployed and tested an API in Cloud Endpoints!

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 quickstart.

What's next

Send feedback about...

Cloud Endpoints