Getting Started with Endpoints on App Engine Flexible Environment

This page shows you how to configure, deploy, and send requests against a sample API running on an instance in the App Engine flexible environment.

Before you begin

  1. Use the Cloud Platform Console to create a new Cloud Platform project, create an App Engine application, and enable billing:

    Go to App Engine

    When prompted, select the region where you want your App Engine application located and then enable billing.

  2. Note the ID of your project, because you'll need it later.

  3. Install cURL for testing purposes. On Windows, this tutorial uses PowerShell's built in WebRequest support.

  4. To deploy your app with the gcloud command-line tool, you must download, install, and initialize the Google Cloud SDK:

    Download the SDK

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

  6. 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 Open API 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.
  2. In the host field, replace the text with the Cloud Endpoints service name. We recommend the following format:
    host: "[YOUR-PROJECT-ID].appspot.com"

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

    host: "example-project.appspot.com"
    

    This name format matches the fully qualified domain name (FQDN) that is created when you deploy the service in the next step. So in this case, both the Endpoints service name and FQDN are the same.

  3. Note that the sample may contain the following: host: "echo-api.endpoints.PROJECT-ID.cloud.goog". This name format matches the recommended service name format for APIs that are deployed on Cloud Endpoints using Container Engine or Compute Engine.

  4. Deploy your Open API configuration file with the following command:
    gcloud service-management deploy openapi.yaml

    This creates a new Cloud Endpoints service with the name that you specified in the host field of the openapi.yaml file (if it does not already exist). The service is updated according to your Open API configuration file. No matter what the Endpoints service name is, for APIs deployed on App Enginge, Service Management creates a DNS record using the name format PROJECT-ID.appspot.com, which is the FQDN that you use when you send requests to the API.

  5. Display the service configuration ID, by entering the following:
    gcloud service-management configs list --service=[YOUR-PROJECT-ID].appspot.com
    
    In the above command, replace [YOUR-PROJECT-ID] with your project ID. Do not include the square brackets.
  6. Edit app.yaml and add the following to enable the Endpoints API Management features on App Engine Flex:
    endpoints_api_service:
      name: "[YOUR-PROJECT-ID].appspot.com"
      config_id: "[YOUR-CONFIG-ID]"
    

    Replace [YOUR-PROJECT-ID] with your project ID, and [YOUR-CONFIG-ID] with the service configuration ID displayed in the previous step. Do not include the square brackets. For example:

    endpoints_api_service:
      name: "example-project.appspot.com"
      config_id: "2017-02-13-r2"
    
  7. Save the app.yaml file. You will need to repeat these steps and update the app.yaml file when you make changes to your Open API specification.

Deploying the sample API

To deploy the sample API, run the following the command from the directory where your configuration file is located:

Java
  1. Make sure you are in the java-docs-samples/endpoints/getting-started directory.
  2. Deploy using Maven:
    mvn appengine:deploy
Python
gcloud app deploy
Go
gcloud app deploy
PHP
gcloud app deploy
Ruby
gcloud app deploy
NodeJS
gcloud app deploy

Sending requests to the API

After deploying the sample API, you can send requests to it.

  1. Export an environment variable for your App Engine project URL:

    • Linux Bash shell: export ENDPOINTS_HOST=https://[YOUR-PROJECT-ID].appspot.com
    • Windows Powershell: $Env:ENDPOINTS_HOST="https://[YOUR-PROJECT-ID].appspot.com

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

  2. Create an API key.

    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..."
  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" "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"
    • In Windows PowerShell:
      (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "$Env:ENDPOINTS_HOST/echo?key=$Env:ENDPOINTS_KEY").Content
  4. View 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.

  5. 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 tutorial.

What's next

Send feedback about...

Cloud Endpoints