Google App Engine

Writing the API: A Simple GET

In this part of the tutorial, you'll create a backend API that has a very simple GET. We'll need to add a JavaBean class called Greeting.

Coding a backend with a simple GET method

To write a simple backend,

  1. In your project, change directory to helloendpoints/helloendpoints-war/src/main/java.

  2. Create the directories using the following command:

    mkdir -p com/google/appengine/samples/helloendpoints
    
  3. Change directory to helloendpoints/helloendpoints-war/src/main/java/com/google/appengine/samples/helloendpoints.

  4. Create a file named HelloGreeting.java, and add the following contents:

    package com.google.appengine.samples.helloendpoints;
    
    public class HelloGreeting {
    
      public String message;
    
      public HelloGreeting() {};
    
      public HelloGreeting(String message) {
        this.message = message;
      }
    
      public String getMessage() {
        return message;
      }
    
      public void setMessage(String message) {
        this.message = message;
      }
    }
    
  5. In that same directory, create a file named Greetings.java and add the following contents:

    package com.google.appengine.samples.helloendpoints;
    
    import com.google.api.server.spi.config.Api;
    import javax.inject.Named;
    import java.util.ArrayList;
    /**
     * Defines v1 of a helloworld API, which provides simple "greeting" methods.
     */
    @Api(name = "helloworld", version = "v1")
    public class Greetings {
      public static ArrayList<HelloGreeting> greetings = new ArrayList<HelloGreeting>();
    
      static {
        greetings.add(new HelloGreeting("hello world!"));
        greetings.add(new HelloGreeting("goodbye world!"));
      }
    
      public HelloGreeting getGreeting(@Named("id") Integer id) {
        return greetings.get(id);
      }
    }
    
  6. Change directory to helloendpoints.

  7. Rebuild by invoking Maven as follows:

    mvn clean install
    

Testing the backend API locally

In this section, you'll use the Google API Explorer to test the backend API. The API Explorer is a Google tool that lets you send requests to a service without having to use a client.

To test the backend API on your local machine:

  1. Change directory to helloendpoints/helloendpoints-ear:

  2. Run the backend by invoking Maven as follows:

    mvn appengine:devserver
    

    When the backend builds and loads successfully this message is displayed:

    INFO: Dev App Server is now running.
    
  3. To send requests to the backend API, visit the API Explorer in your browser at this URL:

    http://localhost:8080/_ah/api/explorer
    

    This opens up the API Explorer for your backend. Notice the list of APIs displayed with helloworld API in that list.

  4. Click helloworld to display the available methods. Notice how the name specified in your @Api annotation (helloworld) is prepended to the API class and method name.

  5. Click helloworld.greetings.getGreetings to display the Explorer form for it:

    greetings.GetGreetings

  6. Our simple backend has two "canned" messages in an array. Get the first message by entering a value of 0 in the Id text box, then click Execute.

    Notice the display of the request and response. In the Response, you'll see the OK result and the returned message, hello world!.

  7. Enter a value of 1 in the Id text box, then click Execute; this time the message is goodbye world!.

Code summary

A class that defines an API can be a plain Java object, inheriting from Object, or it can be part of a complex class hierarchy — the choice is up to you. In this example, we used the Greeting class that inherits from Object.

In the code, notice the imports. 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. If you wanted to create an API that exposes multiple classes, you would use the same @Api annotation for each class. (The name and version would have to be the same for each class). For a list of the attributes available, see @Api: API-Scoped Annotations or the Javadoc for @Api.

Notice that we didn't use the @ApiMethod annotation, because we don't need any special API configuration for the method. The method is public so it is automatically exposed in the API.

Next...

Next, we'll add a simple POST.

Continue to Writing the API: a Simple POST.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.