Writing and annotating the code

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

Before you begin

  1. Set up your development environment.

  2. Clone the skeleton Endpoints Frameworks example:

     git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

  3. The skeleton Endpoints Frameworks example is located in:

     cd appengine-java8/endpoints-v2-skeleton/

To help explain how annotations work, this document uses the endpoints-v2-backend sample to show the annotations and other code that you must add to the endpoints-v2-skeleton sample to get it to build. In the end, the modified endpoints-v2-skeleton sample behaves the same as the endpoints-v2-backend sample, which is used in Getting started with Endpoints Frameworks on App Engine.

Creating and annotating code

To annotate your code:

  1. Change directories to the project's Java source directory, for example: src/main/java/com/example/skeleton.
  2. Create a JavaBean class file named Message.java that contains the following code: 
    public class Message {

  private String message;

  public String getMessage() {
    return this.message;
  }

  public void setMessage(String message) {
    this.message = message;
  }
}
  3. Edit the MyApi.java file contained in the skeleton example. Change the @Api definition annotation with the following: 
    @Api(
    name = "echo",
    version = "v1",
    namespace =
    @ApiNamespace(
        ownerDomain = "echo.example.com",
        ownerName = "echo.example.com",
        packagePath = ""
    ),
    // ...
)

    The version = "v1" attribute specifies the version of the sample API. The value that you enter becomes part of the path in the URL to your API. For more information on versions, see Handling API versioning.

  4. Add the following echo method as your first API endpoint and the doEcho helper method to your MyApi.java. 
    @ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}
     
    private Message doEcho(Message request, Integer n) {
  Message response = new Message();
  if (n != null && n >= 0) {
    StringBuilder sb = new StringBuilder();
    for (int i = 0; i < n; i++) {
      if (i > 0) {
        sb.append(' ');
      }
      sb.append(request.getMessage());
    }
    response.setMessage(sb.toString());
  }
  return response;
}
  5. Copy all of the imports from Echo.java, and paste them in your MyApi.java.

  6. Maven

    Build the project:

    mvn clean package

    Gradle

    Build the project:

    gradle clean build

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 aren't marked with@ApiMethod aren't 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 Endpoints Frameworks annotations, see Annotations and syntax.

What's next