Google Cloud Endpoints helps you create, deploy, protect, monitor, analyze, and serve your APIs using the same infrastructure Google uses for its own APIs. It consists of tools, libraries and capabilities that allow you to generate APIs and client libraries from an App Engine application.

In this short and introductory codelab we will configure, deploy, and send requests to a sample API running on Google App Engine standard using Cloud Endpoints for App Engine in Java 8 and Maven 3.6.0. These tools come pre-installed if you are using Cloud Shell (recommended).

This will involve the following steps :

Codelab-at-a-conference setup

If you see a "request account button" at the top of the main Codelabs window, click it to obtain a temporary account. Otherwise ask one of the staff for a coupon with username/password.

These temporary accounts have existing projects that are set up with billing so that there are no costs associated for you with running this codelab.

Note that all these accounts will be disabled soon after the codelab is over.

Use these credentials to log into the machine or to open a new Google Cloud Console window https://console.cloud.google.com/. Accept the new account Terms of Service and any updates to Terms of Service.

Here's what you should see once logged in:

When presented with this console landing page, please select the only project available. Alternatively, from the console home page, click on "Select a Project" :

Google Cloud Shell

While Google Cloud and Kubernetes can be operated remotely from your laptop, in this codelab we will be using Google Cloud Shell, a command line environment running in the Cloud.

This Debian-based virtual machine is loaded with all the development tools you'll need. It offers a persistent 5GB home directory, and runs on the Google Cloud, greatly enhancing network performance and authentication. This means that all you will need for this codelab is a browser (yes, it works on a Chromebook).

To activate Google Cloud Shell, from the developer console simply click the button on the top right-hand side (it should only take a few moments to provision and connect to the environment):

activateCloudShell.png

Click the "Start Cloud Shell" button:

Screen Shot 2017-06-14 at 10.13.43 PM.png

Once connected to the cloud shell, you should see that you are already authenticated and that the project is already set to your PROJECT_ID :

gcloud auth list

Command output

Credentialed accounts:
 - <myaccount>@<mydomain>.com (active)
gcloud config list project

Command output

[core]
project = <PROJECT_ID>

Cloud Shell also sets some environment variables by default which may be useful as you run future commands.

echo $GOOGLE_CLOUD_PROJECT

Command output

<PROJECT_ID>

If for some reason the project is not set, simply issue the following command :

gcloud config set project <PROJECT_ID>

Looking for your PROJECT_ID? Check out what ID you used in the setup steps or look it up in the console dashboard:

Project_ID.png

IMPORTANT: Finally, set the default zone and project configuration:

gcloud config set compute/zone us-central1-f

You can choose a variety of different zones. Learn more in the Regions & Zones documentation.

Create or select a Cloud Platform project in the Console and then ensure that the project includes an App Engine application by clicking on this link and select the project that you've created in the previous step.

The dashboard opens if an App Engine application already exists in your project. Otherwise, you are prompted to choose the region where you want your App Engine application located. Select "Java" as the language for the App Engine application.

Let's get some sample code from github using Cloud Shell :

$ git clone https://github.com/GoogleCloudPlatform/java-docs-samples
$ cd java-docs-samples/appengine-java8/endpoints-v2-backend

The sample includes the Endpoints Frameworks tool that generates an OpenAPI configuration file that describes the sample code's REST API. Follow the steps in this section to configure and build the sample Maven project so that you can then generate the OpenAPI configuration file.

You must add your project ID to the sample's pom.xml before you can deploy the code. For that edit the file pom.xml, search for <endpoints.project.id> in the <properties> section, and replace the value YOUR_PROJECT_ID with your own :

<endpoints.project.id>example-project</endpoints.project.id>

Let's now build the project with Maven :

$ mvn clean package

[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 14.846s
[INFO] Finished at: Wed April 13 09:43:09 PDT 2019
[INFO] Final Memory: 24M/331M

Let's now use a tool provided by the Cloud Endpoints framework to generate an OpenAPI configuration file called openapi.json. This file describes the REST API from the sample code. To generate the config file, simply invoke the Endpoints Frameworks tool using Maven :

$ mvn endpoints-framework:openApiDocs

Wait for the configuration spec to build. When it finishes you'll see a message similar to this one:

OpenAPI document written to target/openapi-docs/openapi.json

Note the following request paths listed in the generated openapi.json that will serve the requests :

"basePath": "/_ah/api"
 ...
"paths": {
  "/echo/v1/echo": {
...
  "/echo/v1/echo/{n}": {
    "post": {
...

Let's now deploy this Cloud Endpoints configuration to an infrastructure service that will manage APIs and services including services created using Cloud Endpoints.

To deploy the configuration file :

$ gcloud endpoints services deploy target/openapi-docs/openapi.json

This creates a new Cloud Endpoints service with the name in the format YOUR_PROJECT_ID.appspot.com. This name is configured in pom.xml and other configuration files included in the sample.

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.json 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-11-02-r2] uploaded for service [example-project.appspot.com]

So far you have deployed the OpenAPI configuration to Service Management, but you have not yet deployed the code that implements the API backend. This section walks you through deploying the sample API to App Engine. To deploy the API backend:

$ mvn appengine:deploy

Follow the prompts and wait for the upload to finish.

Once you've deployed the API and its configuration file, you can start sending requests to the API. To send a request to the API (replace PROJECT_ID with your own project ID) :

$ curl \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"message":"hello world"}' \
     https://[PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

You should get a 200 response with the following data:

{
 "message": "hello world"
}

Feel free to try out other endpoints described in the OpenAPI document :

$ curl \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"message":"wat"}' \
     https://[PROJECT_ID].appspot.com/_ah/api/echo/v1/echo/10

You have just deployed and tested an API in Cloud Endpoints using the Cloud Endpoints Frameworks!

Cloud Endpoints offers a built-in ability to track the activity on your endpoints.

Activity graphs for your APIs are available in the Endpoints page:

You can also look at the request logs for your API in the Logs Viewer page:

Cloud Endpoints has a lot more in store for you: from handling API versioning and restricting access with API keys to limiting API request with quotas. Check out the how-to guides for details.

You can also use Cloud Endpoints with the OpenAPI Specification, Endpoints Frameworks, or gRPC. See the documentation for choosing the right API Framework.