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.3.9. These tools come pre-installed if you are using Cloud Shell (recommended).

This will involve the following steps :

Self-paced environment setup

If you don't already have a Google Account (Gmail or Google Apps), you must create one. Sign-in to Google Cloud Platform console (console.cloud.google.com) and create a new project:

Remember the project ID, a unique name across all Google Cloud projects (the name above has already been taken and will not work for you, sorry!). It will be referred to later in this codelab as PROJECT_ID.

Next, you'll need to enable billing in the Cloud Console in order to use Google Cloud resources.

Running through this codelab shouldn't cost you more than a few dollars, but it could be more if you decide to use more resources or if you leave them running (see "cleanup" section at the end of this document).

New users of Google Cloud Platform are eligible for a $300 free trial.

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):

Then accept the terms of service and click the "Start Cloud Shell" link:

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>

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:

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.

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/endpoints-frameworks-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 2016
[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 looks at the request logs for your API in the Logs Viewer page:

Let's list the endpoint and delete it by name:

$ gcloud endpoints services list

NAME                                TITLE
YOUR_PROJECT_ID.appspot.com  YOUR_PROJECT_ID.appspot.com

$ gcloud endpoints services delete YOUR_PROJECT_ID.appspot.com

...
Waiting for async operation operations/services.YOUR_PROJECT_ID.appspot.com-2 to complete...
Operation finished successfully.

Note that the above steps will delete the endpoint entry but not the business logic deployed in the App Engine application.

You can also delete the entire project but you would lose any billing setup you have done (disabling project billing first is required). Additionally, deleting a project will only stop all billing after the current billing cycle ends.

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.