This page describes how to structure and annotate your
Cloud Endpoints Frameworks code. For a complete list of all supported
annotations, see
[Annotations](https://docs.cloud.google.com/endpoints/docs/frameworks/java/annotations.md.txt).

## Before you begin

1. [Set up your development environment](https://docs.cloud.google.com/endpoints/docs/frameworks/java/set-up-environment.md.txt).
2. Clone the skeleton Endpoints Frameworks example:

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

   ```java
    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](https://docs.cloud.google.com/endpoints/docs/frameworks/java/get-started-frameworks-java.md.txt).

## 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](https://wikipedia.org/wiki/JavaBeans) class file named `Message.java` that contains the following code:

   ```java
   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:

   ```java
   @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](https://docs.cloud.google.com/endpoints/docs/frameworks/java/handling-api-versioning.md.txt).
4. Add the following `echo` method as your first API endpoint and the `doEcho` helper method to your `MyApi.java`.

   ```java
   @ApiMethod(name = "echo")
   public Message echo(Message message, @Named("n") @Nullable Integer n) {
     return doEcho(message, n);
   }
   ```

   ```java
   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`](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/master/appengine-java8/endpoints-v2-backend/src/main/java/com/example/echo/Echo.java), and paste them in your `MyApi.java`.
6.

   ### Maven

   Build the project:

   ```bash
   mvn clean package
   ```

   ### Gradle

   Build the project:

   ```bash
   gradle clean build
   ```

## Annotation basics

There are three annotations commonly used in backend APIs:

- [`@Api`](https://docs.cloud.google.com/endpoints/docs/frameworks/java/annotations.md.txt#api_api-scoped_annotations) contains the configuration details of the backend API.
- [`@ApiMethod`](https://docs.cloud.google.com/endpoints/docs/frameworks/java/annotations.md.txt#apimethod_method-scoped_annotations) 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`](https://docs.cloud.google.com/endpoints/docs/frameworks/java/annotations.md.txt#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](https://docs.cloud.google.com/endpoints/docs/frameworks/java/annotations.md.txt).

## What's next

- [Learn about adding API management](https://docs.cloud.google.com/endpoints/docs/frameworks/java/adding-api-management.md.txt).
- [Learn about the supported parameter and return types](https://docs.cloud.google.com/endpoints/docs/frameworks/java/parameter-and-return-types.md.txt).
- [Learn about exceptions and status codes](https://docs.cloud.google.com/endpoints/docs/frameworks/java/exceptions.md.txt).