Writing and Annotating the Code

This page describes the basics of 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. This document expects that you cloned the skeleton Endpoints Framework example:

     git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
    
  3. The skeleton Endpoints Framework example is located in:

     cd appengine-java8/endpoints-v2-skeleton/
    

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 file MyApi.java 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 = ""
        ),
        // ...
    )
  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 message, Integer n) {
      if (n != null && n >= 0) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < n; i++) {
          if (i > 0) {
            sb.append(" ");
          }
          sb.append(message.getMessage());
        }
        message.setMessage(sb.toString());
      }
      return message;
    }
  5. Maven

    Build the project with the following command.

    mvn clean package

    Gradle

    Build the project with the following command.

    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 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 Frameworks annotations, see Annotations and Syntax.

What's next

Send feedback about...

Cloud Endpoints Frameworks for App Engine