Writing and Annotating the Code

This page describes the basics of how to structure and annotate your Cloud Endpoints code. For a complete list of all supported annotations, see Endpoint Annotations.

The recommended way to add a backend API to a new or existing Android app is to use Android Studio and Cloud Tools for Android Studio; Android Studio automatically generates starter code for you, complete with annotations. If you are building an iOS or Javascript app you can use Maven and manually write and annotate the code.

Before you begin

Set up your development environment.

Creating and annotating starter code

To annotate your code:

Android Studio

Follow the instructions for Adding a Cloud Endpoints Module in the Cloud Tools for Android Studio documentation.

This generates a new module which contains a JavaBean class, MyBean.java which contains the data object model.

/** The object model for the data we are sending through endpoints */
public class MyBean {

  private String myData;

  public String getData() {
    return myData;
  }

  public void setData(String data) {
    myData = data;
  }
}

It also generates a class, MyEndpoint.java, that contains starter code for your backend API.

/** An endpoint class we are exposing */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""),
    clientIds = {Constants.WEB_CLIENT_ID, Constants.ANDROID_CLIENT_ID, Constants.IOS_CLIENT_ID},
    audiences = {Constants.ANDROID_AUDIENCE})
/** A simple endpoint method that takes a name and says Hi back */
@ApiMethod(name = "sayHi")
public MyBean sayHi(@Named("name") String name) {
  MyBean response = new MyBean();
  response.setData("Hi, " + name);

  return response;
}

For step-by-step instructions on connecting your Android application to this backend module, see App Engine Java Endpoints Module template documentation.

Maven

  1. Change directories to the project's Java source directory, for example: /src/main/java/com/example/backend.
  2. Create a JavaBean class file named MyBean.java that contains the following code, replacing com.example.backend with your package name.
    /** The object model for the data we are sending through endpoints */
    public class MyBean {
    
      private String myData;
    
      public String getData() {
        return myData;
      }
    
      public void setData(String data) {
        myData = data;
      }
    }

    It also generates a class, MyEndpoint.java, that contains starter code for your backend API.

  3. Edit the file YourFirstAPI.java that was created when you set up the development environment. Change the file's contents to the following code, replacing com.example.backend with your package name.
    /** An endpoint class we are exposing */
    @Api(name = "myApi",
        version = "v1",
        namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
            ownerName = "helloworld.example.com",
            packagePath = ""),
        clientIds = {Constants.WEB_CLIENT_ID, Constants.ANDROID_CLIENT_ID, Constants.IOS_CLIENT_ID},
        audiences = {Constants.ANDROID_AUDIENCE})
    /** A simple endpoint method that takes a name and says Hi back */
    @ApiMethod(name = "sayHi")
    public MyBean sayHi(@Named("name") String name) {
      MyBean response = new MyBean();
      response.setData("Hi, " + name);
    
      return response;
    }
  4. Build the project with the following command.
    mvn clean install
    

Annotation basics

There are three annotations commonly used in backend APIs:

  • @Api contains the configuration details of the backend API.
  • @ApiMethod marks a class method that is part of the backend API. Methods that are not marked with @ApiMethod are not included when you generate client libraries and discovery docs. The @ApiMethod annotation can also be used to override the API configuration for a specific method.
  • @Named must be added to all parameters passed to server-side methods, unless the parameter is an entity type.

For a complete list of all Cloud Endpoints annotations, see Annotations and Syntax.

What's next