In this tutorial, you'll go through a code walkthrough of a Maven project containing a complete Cloud Endpoints backend API and a sample web client that accesses the API. This sample demonstrates many of the core features supported for backend APIs:
- A simple HTTP
GETmethod that retrieves one of two canned responses based on the user's choice (Get Greeting).
- A simple HTTP
GETmethod that retrieves all of the canned responses (List Greeting).
- A POST method that provides a user-supplied greeting and multiplier to the backend API which then returns the greeting repeated the number of times specified by the multiplier (Multiply Greeting).
- An OAuth protected method that requires a signed-in user, which returns the user's email address (Authenticated Greeting).
This walkthrough focuses on the backend API, and doesn't go into detail about the web client included with the project. You can find a full description of the web client in the web client tutorial.
The UI provided by the web client included with the sample project looks like this:
A complete Hello Endpoints backend API that demonstrates common tasks, such as:
- Handling HTTP
- Handling HTTP
- Protecting methods with OAuth 2.0
- Deploying the backend API to production App Engine
App Engine has free a level of usage. If your total usage of App Engine is less than the limits specified in the App Engine free quota, there is no charge for doing this tutorial.
Before you begin
- Familiarize yourself with Java.
- Install the Java 7 SDK and set up your environment as described in Configuring Java.
- Install Maven 3.1 or greater as described in Installing Maven 3.1+.
Sign in to your Google account.
If you don't already have one, sign up for a new account.
- Select or create a Cloud Platform Console project.
- Make a note of the project ID because you'll need to use it later.
Cloning the sample project
Clone the Hello Endpoints sample from GitHub:
git clone https://github.com/GoogleCloudPlatform/appengine-endpoints-helloendpoints-java-maven
Alternatively, you can download the sample as a zip file and extract it.
Viewing the project layout and files
If you execute a
tree command or equivalent on the directory
appengine-endpoints-helloendpoints-java-maven, the following represents the
structure of the project:
You'll learn about these these files during the walkthrough:
||Used to specify the project ID and the application version.|
||Does all the mappings required for the backend API servlet.|
||Contains CSS for the sample web client. Not required, but used for this demo.|
||The sample web client for this backend API.|
||Contains client IDs used for clients and authorization.|
||The backend API servlet.|
||The JavaBean used to send Greetings data through the endpoint.|
Creating OAuth 2.0 client IDs for the backend
You need to create a client ID for each client, in this example for the web
client. The client ID is added to the backend API (in
Constants.java) and to
the web client.
To create a client ID:
Open the Credentials page for your project:
Go to the Credentials page
Click Create credentials > OAuth client ID.
Click Configure consent screen
Supply a product name, which you can change later, and click Save.
Select Web application as the application type to display the settings for web clients.
Specify a name for the web client.
your_project_idwith your actual App Engine project ID. Be sure to specify
https://in the URL, not
Note the client ID that is generated. This is the client ID you need to use in your backend and in your client application. You can always return to the Credentials page later to view the client ID.
Adding the client ID to backend API and to web client
To add the client ID to backend and client:
Edit the file
WEB_CLIENT_ID, replace the value
replace this with your web client IDwith the client ID, and save your changes. Ignore the constants for Android and iOS because you won't use these in this walkthrough.
Edit the file
Edit the line starting with
google.devrel.samples.hello.CLIENT_ID =so that it contains the client ID.
Adding the project ID to the application
You must add the project ID obtained when you created your project to your app before you can deploy.
To add the project ID:
Edit the file
<application>, replace the value
your-app-idwith your project ID.
Save your changes.
Building and running the API locally
To build and run the backend API, and test it locally using the sample web client:
In the root directory of the project,
appengine-endpoints-helloendpoints-java-maven/build the project by invoking the command
mvn clean install
Wait for the project to build. When the project successfully finishes, you will see a message similar to this one:
[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
Start the app in the local development server by invoking:
In your browser, visit the URL http://localhost:8080 to view the web client app.
In the Greeting ID text box, supply a value of
1, then click Submit. (The sample backend has only two stored messages.) You'll see hello world! or goodbye world!, depending on the value.
Under List Greetings, click Submit to list out those same two stored greetings.
Under Multiply Greetings, supply any text in the Greeting textbox and the number of repetitions in the Count textbox, then click Submit.
Note that the Authenticated Greeting feature only works in deployment.
- Edit the file
<application>to the project ID you obtained earlier during Setup. (Or, look up the Client ID for web application in the Google Cloud Platform Console.)
Deploying to App Engine
After you finish testing, you can deploy to App Engine:
To deploy to App Engine:
From the main project directory,
helloendpoints/, invoke the command
Follow the prompts: when you are presented with a browser window containing a code, copy it to the terminal window.
If you don't see the web client app, or if the client doesn't behave as expected, check for a successful deployment.
Hello Endpoints code walkthrough
In this part of the tutorial, you'll learn more about the code in the sample backend API.
The following imports are needed for the backend API, in
package com.example.helloendpoints; import com.google.api.server.spi.config.Api; import com.google.api.server.spi.config.ApiMethod; import com.google.api.server.spi.response.NotFoundException; import com.google.appengine.api.users.User; import java.util.ArrayList; import javax.inject.Named;
You must always import
com.google.api.server.spi.config.Api because you must always annotate your
API class with @Api,
as shown in the snippet. This sample also imports
com.google.api.server.spi.config.ApiMethod to illustrate its
use in changing the name of a method, but this is optional; all public methods
of the class with the
@Api annotation are automatically exposed in the backend API.
The sample imports
com.google.appengine.api.users.User because it has a method
protected by OAuth 2.0. The import
import javax.inject.Named is required for the request parameters.
API definition configuration using
Let's look at the
@Api annotation in