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/

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 should behave the same as the endpoints-v2-backend sample, which is used in the tutorial 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 file MyApi.java contained in the skeleton example. Change the @Api definition annotation with the following:
        name = "echo",
        version = "v1",
        namespace =
            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 message, Integer n) {
      if (n != null && n >= 0) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < n; i++) {
          if (i > 0) {
            sb.append(" ");
      return message;
  5. Copy all of the imports from Echo.java, and paste them in your MyApi.java.
  6. Maven

    Build the project with the following command.

    mvn clean package


    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

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine
Need help? Visit our support page.