Hello Endpoints Code Walkthrough

Imports

Here are the imports for Greetings.java:

src/main/java/com/example/helloendpoints/Greetings.java

View on GitHub

\[This section requires a browser that supports JavaScript and iframes.\]

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. In this sample, we also import com.google.api.server.spi.config.ApiMethod because we want 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.

We import com.google.appengine.api.users.User because we have a method protected by OAuth, and this import is required for that. We also import import javax.inject.Named because we need it for our request parameters.

API definition (configuration) using @Api

Let's look at the @Api annotation in Greetings.java:

src/main/java/com/example/helloendpoints/Greetings.java

View on GitHub

\[This section requires a browser that supports JavaScript and iframes.\]

This API is implemented in the single class called Greetings, with the API name and version always required. If you need to create an API that exposes multiple classes, you must use the same @Api annotation for each class. (The name and version would have to be identical for each class). For details on the attributes available, see @Api: API-Scoped Annotations or the Javadoc for @Api.

The sample protects a method by OAuth, which means that the scopes attribute is required; this must be set to the value https://www.googleapis.com/auth/userinfo.email, which is what Constants.EMAIL_SCOPE resolves to. (This scope lets OAuth work with Google Accounts.)

Also, because of the OAuth protection, we must supply a list of clients allowed to access the protected method in the clientIDs attribute. The sample suggests one way to do this, with lists of client IDs in the Constants.java file. So far, we have supplied a valid web client ID via Constants.java, but we have dummy values for Android and iOS clients to show that this client ID list could contain all the supported clients. Only clients in this list can access the protected method.

The audiences attribute is set to the backend API's web client. This attribute must be set if there are any Android clients; it is not used for non-Android clients.

Inside the class, notice the lines that set up an ArrayList of stored HelloGreeting (defined in HelloGreeting.java) JavaBean objects that are returned from the methods. In Endpoints, methods can only return Objects (treated as JavaBean objects) or a collection of Objects, which are converted to JSON to form the response.

A simple GET

The following lines return text greetings. Both getGreeting and listGreeting are public, so they will be exposed in the backend API:

src/main/java/com/example/helloendpoints/Greetings.java

View on GitHub

\[This section requires a browser that supports JavaScript and iframes.\]

The getGreeting method serves an incoming GET request that has a numeric value indicating the user's choice of greeting:

• A value of 0 returning the first value, hello world!.

• A value of 1 returning the second value, goodbye world!.

All other values will return an error. Notice that the @Named attribute must be used for the incoming parameter since it is not an entity type.

The listGreeting method returns all the stored greetings in the array list.

A simple POST

The following lines of code handle an incoming POST request containing a user-supplied greeting and integer, and returns the greeting repeated the number of times specified by the integer:

src/main/java/com/example/helloendpoints/Greetings.java

View on GitHub

\[This section requires a browser that supports JavaScript and iframes.\]

This method is annotated by @ApiMethod so we can override the default name that is generated by Endpoints. Notice that Endpoints prepends the class name (greetings, lowercase) to the method name when it generates the method name in the backend API: greetings.insertGreeting. When we override this value using the method annotation, the prepending does not take place, so we need to add the class prepending manually in our code: greetings.multiply to make it consistent with the other backend API method names.

The method annotation can perform other API overrides as well; for more details, see @ApiMethod: Method-Scoped Annotations.

OAuth Protecting a method

Any client can access your Endpoints API methods unless you protect them with OAuth 2.0. In some scenarios, you may want to restrict access to some or all of the API methods.

To protect a method in the backend API, you need to do the following:

• Add required support in the @Api annotation as described above:

  • Add scopes set to the email scope.

  • Add clientIds containing the client whitelist.

  • For Android devices only, specify audiences.

• Add a User parameter to the method you wish to protect.

The code you copied already has the required annotations, so look at the code with the added User parameter:

src/main/java/com/example/helloendpoints/Greetings.java

View on GitHub

\[This section requires a browser that supports JavaScript and iframes.\]

When you declare a parameter of type User in your API method as shown in the snippet above, the API backend framework automatically authenticates the user and enforces the authorized clientIds whitelist, ultimately by supplying the valid User or not.

If the request coming in from the client has a valid auth token or is in the list of authorized clientIDs, the backend framework supplies a valid User to the parameter. If the incoming request does not have a valid auth token or if the client is not on the clientIDs whitelist, the framework sets User to null. Your own code must handle both the case where User is null and the case where there is a valid User. If there is no User, for example, you could choose to return a not-authenticated error or perform some other desired action.

Done with the tutorial: what's next?

Now that you've created your first backend APIs, take a deeper dive into backend API features and configurations, and you may want to hook up other App Engine services to your backend API, such as the Datastore. You can learn more by visiting the following resources:

• Annotating Your Code; which covers all of the API configuration and features.

• The Tic-Tac-Toe sample; which shows how to build a backend that uses the Datastore.