Cloud Endpoints Quickstart

This page walks you through deploying a sample API with Google Cloud Endpoints. The sample code includes:

  • A REST API that you can query to find the name of an airport from its three-letter IATA code.
  • A script that uploads the API configuration to Cloud Endpoints.
  • A script that deploys a Google App Engine flexible backend to host the sample API.

After you send some requests to the sample API, you can view the Cloud Endpoints Activity Graphs and Logs, tools that allow you to monitor your APIs and gain insights into their usage.

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

Starting Cloud Shell

  1. Click the Activate Google Cloud Shell button at the top of the console window. Activate Google Cloud Shell

    A Cloud Shell session opens inside a new frame at the bottom of the console and displays a command-line prompt. It can take a few seconds for the shell session to be initialized.

    Cloud Shell session
  2. Enter the following in Cloud Shell to display the project IDs for your projects:
    gcloud projects list
  3. Set the default project to the one that your are using for this Quickstart.
    gcloud config set project [YOUR-PROJECT-ID]

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

Getting the sample code

  1. Enter the following command in Cloud Shell to get the sample API and scripts:

    git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
    
  2. Change to the directory that contains the sample code:

    cd endpoints-quickstart
    

Deploying the Endpoints Configuration

To publish a REST API to Endpoints, an OpenAPI configuration file that describes the API is required. The sample API comes with a pre-configured OpenAPI file called openapi.yaml.

Cloud Endpoints uses Google Service Management, an infrastructure service of Cloud Platform to create and manage APIs and services. To use Endpoints to manage an API, you deploy the API's OpenAPI configuration to Service Management.

To deploy the Endpoints configuration:

  1. In the endpoints-quickstart directory, enter the following in Cloud Shell:

    cd scripts
    
  2. Run the following script, which is included in the sample:

    ./deploy_api.sh
    

Cloud Endpoints uses the host field in the OpenAPI configuration file to identify the service. The deploy_api.sh script sets the ID of your Cloud project as part of the name configured in the host field. (When you prepare an OpenAPI configuration file for your own service, you will need to do this manually.)

The script then deploys the OpenAPI configuration to Service Management using the command: gcloud endpoints services deploy openapi.yaml

As it is creating and configuring the service, Service Management outputs a great deal of information to the console. You can safely ignore the warnings about the paths in openapi.yaml not requiring an API key. On successful completion, you 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 [airports-api.endpoints.example-project.cloud.goog]

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. The deploy_app.sh script included in the sample creates an App Engine flexible environment to host the API backend, and then the script deploys the API to App Engine.

To deploy the API backend:

In the endpoints-quickstart/scripts directory, run the following script:

./deploy_app.sh

The script runs the following command to create an App Engine flexible environment in the us-central region: gcloud app create --region="$REGION"

It takes a several seconds to create the App Engine flexible backend. You'll see the following displayed on the console after the App Engine is created:

Success! The app is now created. Please use `gcloud app deploy` to deploy your first app.

Next, the script runs the gcloud app deploy command to deploy the sample API to App Engine.

You'll see a line like the following in the console:

Deploying ../app/app_template.yaml...You are about to deploy the following services:

It takes several minutes for the API to be deployed to App Engine. You'll see a line like the following when the API is successfully deployed to App Engine:

Deployed service [default] to [https://example-project.appspot.com]

Sending Requests to the API

After deploying the sample API, you can send requests to it by running the following script:

./query_api.sh

The script echoes the curl command that it uses to send a request to the API, and then displays the result. You'll see something like the following on the console:

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

The API expects one query parameter, iataCode, that is set to a valid IATA airport code such as SEA or JFK. For example:

./query_api.sh JFK

Note: App Engine may take a few minutes to respond successfully to requests. If you send a request and get back an HTTP 502, 503, or some other server error, wait a minute and try the request again.

You just deployed and tested an API in Cloud Endpoints!

Tracking API activity

With APIs deployed with Cloud Endpoints, you can monitor critical operations metrics in Google Cloud Platform Console, and gain insight into your users and usage with Stackdriver Logging.

  1. Run the traffic generation script to populate the graphs and logs.

    ./generate_traffic.sh
    
  2. Look at the activity graphs for your API in the Endpoints page.
    View Endpoints activity graphs

    It may take a few moments for the requests to be reflected in the graphs. While you wait for data to be displayed:

    • If the Permissions side panel is not open, click +Permissions. The Permissions panel allows you to control who has access to your API and the level of access.

    • Click Deployment history. This tab displays a history of your API deployments, including the deployment time and who deployed the change.

    • Click Overview. You should see the traffic coming in. After the traffic generation script has been running for a minute, you should see three lines on the Total latency graph (50th, 95th, and 98th percentiles). This data provides a quick estimate of response times.

  3. Scroll down to the bottom of the Endpoints graphs, and under Method, click GET/airportName. The Logs Viewer page displays the request logs for the API.

  4. Click the Activate Google Cloud Shell button at the top of the console window to display the Cloud Shell.

  5. Enter Ctrl-C to stop the script.

Add a Quota to the API

Cloud Endpoints lets you set quotas that let you control the rate at which applications can call your API. You can use quotas to protect your API from excessive usage by a single client.

  1. Deploy the Endpoints configuration that has a quota.

    ./deploy_api.sh ../openapi_with_ratelimit.yaml
    
  2. Redeploy your app to use the new Endpoints configuration.

    ./deploy_app.sh
    
  3. Navigate to the Credentials page.
    Credentials

  4. Click Create credentials and choose API key. A new API key is displayed on the screen. Click the double rectangle icon to copy it to your clipboard.

  5. In Cloud Shell, type the following. Replace YOUR-API-KEY with the API key you just created.

    export API_KEY=YOUR-API-KEY
    
  6. Send your API a request using the API key you just generated.

    ./query_api_with_key.sh $API_KEY
    

    You'll see something like the following on the console:

    curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
    San Francisco International Airport
    

  7. The API now has a limit of 5 requests per second. Run the following command to send traffic to the API and trigger the quota limit.

    ./generate_traffic_with_key.sh $API_KEY
    
  8. After running the script for 5-10 seconds, enter Ctrl-C to stop the script.

  9. Send another authenticated request to the API.

    ./query_api_with_key.sh $API_key
    

You'll see something like the following on the console:

{
 "code": 8,
 "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer 'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
 "details": [
  {
   "@type": "type.googleapis.com/google.rpc.DebugInfo",
   "stackEntries": [],
   "detail": "internal"
  }
 ]
}

If you get a different response, try running the generate_traffic_with_key.sh script again and then retry.

Congratulations! You've successfully rate-limited your API. You can also set varying limits on different API methods, create multiple kinds of quotas, and keep track of which consumers use which APIs.

View Endpoints activity graphs

For more information about quotas, see the following:

Clean up

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

./delete_project.sh

Note that the script deletes the entire project.

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