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 src/main/java/com/google/appengine/samples/helloendpoints.

2. 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;
     }
   }
   

3. 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);
     }
   }
   

4. Run the backend you just created by changing to the directory containing the pom.xml file and starting the app in the development server by invoking the Maven plugin command

   mvn appengine:devserver
   

5. When the backend builds and loads successfully this message is displayed: INFO: Dev App Server is now running. In your browser, visit the URL

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

6. This opens up the API Explorer for your backend. Notice the list of APIs displayed with helloworld API in that list. 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. Click helloworld.greetings.getGreetings to display the Explorer form for it:

   

7. 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.

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

9. 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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.