Cloud Endpoints Frameworks annotations and syntax

The Endpoints Frameworks annotations describe API configuration, methods, parameters, and other vital details that define the properties and behavior of the endpoint.

See Writing and annotating code for information on adding annotations by using a Maven project. Maven App Engine Cloud Endpoints artifacts are provided to create and build a backend API, and generate a client library from it.

The annotation that specifies configuration and behavior across the entire API (affecting all the classes exposed in the API and all their exposed methods) is @Api . All public, non-static, non-bridge methods of a class annotated with @Api are exposed in the public API.

If you need special API configuration for a particular method, you can optionally use @ApiMethod to set configuration on a per-method basis. You configure these annotations by setting various attributes, as shown in the following tables.

@Api : API-scoped annotations

The annotation @Api configures the whole API, and applies to all public methods of a class unless overridden by @ApiMethod .

To override a given @Api annotation for a specific class within an API, see @ApiClass and @ApiReference .

Required imports

To use this feature, you need the following import:

  import 
  
 com.google.api.server.spi.config.Api 
 ; 
 

Attributes

Sample @Api annotation

This annotation is placed before the class definition:

  /** An endpoint class we are exposing. */ 
 @Api 
 ( 
 name 
  
 = 
  
 "myApi" 
 , 
  
 version 
  
 = 
  
 "v1" 
 , 
  
 namespace 
  
 = 
  
 @ApiNamespace 
 ( 
 ownerDomain 
  
 = 
  
 "helloworld.example.com" 
 , 
  
 ownerName 
  
 = 
  
 "helloworld.example.com" 
 , 
  
 packagePath 
  
 = 
  
 "" 
 )) 
 

Client IDs and audiences

For OAuth2 authentication, an OAuth2 token is issued to a specific client ID, which means that you can use the client ID to restrict access to your APIs. When you register an Android application in the Google Cloud console, you create a client ID for it. This client ID is the one requesting an OAuth2 token from Google for authentication purposes. When the backend API is protected by auth, an OAuth2 access token is sent and opened by Endpoints, the client ID is extracted from the token, and then the ID is compared to the backend's declared acceptable client ID list (the clientIds list).

If you want your Endpoints API to authenticate callers, you need to supply a list of clientIds that are allowed to request tokens. This list should consist of the all client IDs you have obtained through the Google Cloud console for your web or Android clients. This means that the clients must be known at API build-time. If you specify an empty list, {} , then no clients can access the methods protected by Auth.

If you use the clientIds attribute and you want to test authenticated calls to your API using the Google API Explorer, you must supply its client ID in the list of clientIds : the value to use is com.google.api.server.spi.Constant.API_EXPLORER_CLIENT_ID .

About audiences

The clientIds list protects the backend API from unauthorized clients. But further protection is needed to protect the clients , so that their auth token only works for the intended backend API. For Android clients, this mechanism is the audiences attribute, in which you specify the client ID of the backend API.

Note that when you create a Google Cloud console project, a default client ID is automatically created and named for use by the project. When you upload your backend API into App Engine, it uses that client ID. This is the web client ID mentioned in API authentication .

@ApiMethod : Method-scoped annotations

The annotation @ApiMethod is used to supply a different API configuration than the defaults provided by the @Api or @ApiClass annotations. Note that this is optional: all public, non-static, and non-bridge methods in a class with an @Api annotation are exposed in the API, whether they have an @ApiMethod annotation or not.

Attributes within this annotation allow you to configure details of a single API method. If the same attribute is specified in @Api and @ApiMethod , @ApiMethod overrides.

Required imports

To use this feature, you need the following imports:

  import 
  
 com.google.api.server.spi.config.AnnotationBoolean 
 ; 
 import 
  
 com.google.api.server.spi.config.ApiMethod 
 ; 
 import 
  
 com.google.api.server.spi.config.ApiMethod.HttpMethod 
 ; 
 

Attributes

Sample @ApiMethod annotation

This annotation is placed before the method definition inside a class:

  /** A simple endpoint method that takes a name and says Hi back. */ 
 @ApiMethod 
 ( 
  
 name 
  
 = 
  
 "sayHiUser" 
 , 
  
 httpMethod 
  
 = 
  
 ApiMethod 
 . 
 HttpMethod 
 . 
 GET 
 ) 
 public 
  
 MyBean 
  
 sayHiUser 
 ( 
 @Named 
 ( 
 "name" 
 ) 
  
 String 
  
 name 
 , 
  
 User 
  
 user 
 ) 
  
 throws 
  
 OAuthRequestException 
 , 
  
 IOException 
  
 { 
  
 MyBean 
  
 response 
  
 = 
  
 new 
  
 MyBean 
 (); 
  
 response 
 . 
 setData 
 ( 
 "Hi, " 
  
 + 
  
 name 
  
 + 
  
 "(" 
  
 + 
  
 user 
 . 
 getEmail 
 () 
  
 + 
  
 ")" 
 ); 
  
 return 
  
 response 
 ; 
 } 
 

Methods that take an entity as a parameter should use HttpMethod.POST (for insert operations) or HttpMethod.PUT (for update operations):

  @ApiMethod 
 ( 
  
 name 
  
 = 
  
 "mybean.insert" 
 , 
  
 path 
  
 = 
  
 "mybean" 
 , 
  
 httpMethod 
  
 = 
  
 ApiMethod 
 . 
 HttpMethod 
 . 
 POST 
 ) 
 public 
  
 void 
  
 insertFoo 
 ( 
 MyBean 
  
 foo 
 ) 
  
 { 
 } 
 

@Named

The @Named annotation is required for all non-entity type parameters passed to server-side methods. This annotation indicates the name of the parameter in the request that gets injected here. A parameter that isn't annotated with @Named is injected with the whole request object.

Required imports

To use this feature, you need the following imports:

  import 
  
 javax.inject.Named 
 ; 
 

This sample shows the use of @Named :

  /** 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 
 ; 
 } 
 

where @Named specifies that only the id parameter is injected in the request.

@ApiLimitMetric

This section describes the annotations required to define quotas for your API. See Configuring quotas for all the steps required to setup a quota.

You assign the @ApiLimitMetric annotation to the limitDefinitions attribute of the API-scoped annotations . You must also add @ApiMetricCost to the @ApiMethod annotations for each method that you want to apply a quota to.

Required imports

To use this feature, you need the following import:

  import 
  
 com.google.api.server.spi.config.ApiLimitMetric 
 ; 
 

Attributes

Example

  limitDefinitions 
  
 = 
  
 { 
  
 @ApiLimitMetric 
 ( 
  
 name 
  
 = 
  
 "read-requests" 
 , 
  
 displayName 
  
 = 
  
 "Read requests" 
 , 
  
 limit 
  
 = 
  
 1000 
 ), 
  
 @ApiLimitMetric 
 ( 
  
 name 
  
 = 
  
 "write-requests" 
 , 
  
 displayName 
  
 = 
  
 "Write requests" 
 , 
  
 limit 
  
 = 
  
 50 
 ), 
  
 } 
 

@ApiNamespace

The @ApiNamespace annotation causes the generated client libraries to have the namespace you specify, rather than a default constructed during client library generation.

By default, if you don't use this annotation, the namespace that is used is the reverse of your-project-id.appspot.com . That is, the package path is com.appspot.your-project-id.yourApi .

You can change the default namespace by supplying the @ApiNamespace annotation within the @Api annotation:

  /** An endpoint class we are exposing. */ 
 @Api 
 ( 
 name 
  
 = 
  
 "myApi" 
 , 
  
 version 
  
 = 
  
 "v1" 
 , 
  
 namespace 
  
 = 
  
 @ApiNamespace 
 ( 
 ownerDomain 
  
 = 
  
 "helloworld.example.com" 
 , 
  
 ownerName 
  
 = 
  
 "helloworld.example.com" 
 , 
  
 packagePath 
  
 = 
  
 "" 
 )) 
 

Set the ownerDomain attribute to your own company domain and ownerName to your company name, for example, your-company.com . The reverse of the ownerDomain is used for the package path: com.your-company.yourApi .

You can optionally use the packagePath attribute to provide further scoping. For example, by setting packagePath to cloud , the package path used in the client library is com.your-company.cloud.yourApi . You can add more values to the package path by supplying the delimiter / : packagePath="cloud/platform" .

@Nullable

This annotation indicates that a parameter of a method is optional (and therefore a query parameter). @Nullable may only be used with @Named parameters.

@ApiClass

In a multiclass API , you can use @ApiClass to specify different properties for a given class, overriding equivalent properties in the @Api configuration. See Using @ApiClass for properties that can differ between classes for a complete description of this annotation.

@ApiReference

In a multiclass API , you can use @ApiReference to supply an alternate method of annotation inheritance. See Using @ApiReference inheritance for a complete description of this annotation.

@ApiResourceProperty

@ApiResourceProperty provides control over how resource properties are exposed in the API. You can use it on a property getter or setter to omit the property from an API resource. You can also use it on the field itself, if the field is private, to expose it in the API. You can also use this annotation to change the name of a property in an API resource.

Required imports

To use this feature, you need the following imports:

  import 
  
 com.google.api.server.spi.config.ApiResourceProperty 
 ; 
 import 
  
 com.google.api.server.spi.config.AnnotationBoolean 
 ; 
 

Attributes

Sample class with @ApiResourceProperty

The following snippet shows a class with property getters annotated with @ApiResourceProperty :

  class 
 Resp 
  
 { 
  
 private 
  
 String 
  
 foobar 
  
 = 
  
 "foobar" 
 ; 
  
 private 
  
 String 
  
 bin 
  
 = 
  
 "bin" 
 ; 
  
 @ApiResourceProperty 
  
 private 
  
 String 
  
 visible 
  
 = 
  
 "nothidden" 
 ; 
  
 @ApiResourceProperty 
 ( 
 ignored 
  
 = 
  
 AnnotationBoolean 
 . 
 TRUE 
 ) 
  
 public 
  
 String 
  
 getBin 
 () 
  
 { 
  
 return 
  
 bin 
 ; 
  
 } 
  
 public 
  
 void 
  
 setBin 
 ( 
 String 
  
 bin 
 ) 
  
 { 
  
 this 
 . 
 bin 
  
 = 
  
 bin 
 ; 
  
 } 
  
 @ApiResourceProperty 
 ( 
 name 
  
 = 
  
 "baz" 
 ) 
  
 public 
  
 String 
  
 getFoobar 
 () 
  
 { 
  
 return 
  
 foobar 
 ; 
  
 } 
  
 public 
  
 void 
  
 setFoobar 
 ( 
 String 
  
 foobar 
 ) 
  
 { 
  
 this 
 . 
 foobar 
  
 = 
  
 foobar 
 ; 
  
 } 
 } 
 public 
  
 Resp 
  
 getResp 
 () 
  
 { 
  
 return 
  
 new 
  
 Resp 
 (); 
 } 
 

In the preceding code snippet, @ApiResourceProperty is applied to the getBin getter for the bin property, with the ignored attribute setting telling Endpoints Frameworks to omit this property in the API resource.

@ApiResourceProperty is also applied to the private field visible , which has no getter or setter. Using this annotation exposes this field as a property in the API resource.

In the same snippet, @ApiResourceProperty is also applied to a different getter, getFoobar , which returns a property value for the foobar property. The name attribute in this annotation tells Endpoints Frameworks to change the property name in the API resource. The property value itself is unchanged.

In the preceding example snippet, the JSON representation of a Resp object looks similar to this:

  { 
 "baz" 
 : 
  
 "foobar" 
 , 
  
 "visible" 
 : 
  
 "nothidden" 
 } 
 

@ApiTransformer

The @ApiTransformer annotation customizes how a type is exposed in Endpoints through transformation to and from another type. (The transformer specified must be an implementation of com.google.api.server.spi.config.Transformer .)

Using the @ApiTransformer annotation on a class is the preferred way to specify a transformer. However, you can alternatively specify your custom transformer in the transformer attribute of the @Api annotation.

Required imports

To use this feature, you need the following import:

  import 
  
 com.google.api.server.spi.config.ApiTransformer 
 ; 
 

Sample class with @ApiTransformer

The following snippet shows a class annotated with @ApiTransformer :

  @ApiTransformer 
 ( 
 BarTransformer 
 . 
 class 
 ) 
 public 
  
 class 
 Bar 
  
 { 
  
 private 
  
 final 
  
 int 
  
 x 
 ; 
  
 private 
  
 final 
  
 int 
  
 y 
 ; 
  
 public 
  
 Bar 
 ( 
 int 
  
 x 
 , 
  
 int 
  
 y 
 ) 
  
 { 
  
 this 
 . 
 x 
  
 = 
  
 x 
 ; 
  
 this 
 . 
 y 
  
 = 
  
 y 
 ; 
  
 } 
  
 public 
  
 int 
  
 getX 
 () 
  
 { 
  
 return 
  
 x 
 ; 
  
 } 
  
 public 
  
 int 
  
 getY 
 () 
  
 { 
  
 return 
  
 y 
 ; 
  
 } 
 } 
 

This class is transformed by the BarTransformer class.

Sample Endpoints transformer class

The following snippet shows a sample transformer class named BarTransformer . This is the transformer referenced by @ApiTransformer in the preceding snippet:

  public 
  
 class 
 BarTransformer 
  
 implements 
  
 Transformer<Bar 
 , 
  
 String 
>  
 { 
  
 public 
  
 String 
  
 transformTo 
 ( 
 Bar 
  
 in 
 ) 
  
 { 
  
 return 
  
 in 
 . 
 getX 
 () 
  
 + 
  
 "," 
  
 + 
  
 in 
 . 
 getY 
 (); 
  
 } 
  
 public 
  
 Bar 
  
 transformFrom 
 ( 
 String 
  
 in 
 ) 
  
 { 
  
 String 
 [] 
  
 xy 
  
 = 
  
 in 
 . 
 split 
 ( 
 "," 
 ); 
  
 return 
  
 new 
  
 Bar 
 ( 
 Integer 
 . 
 parseInt 
 ( 
 xy 
 [ 
 0 
 ] 
 ), 
  
 Integer 
 . 
 parseInt 
 ( 
 xy 
 [ 
 1 
 ] 
 )); 
  
 } 
 } 
 

Assuming there is an object with a property bar of type Bar , without the preceding transformer, the object is represented as:

  { 
 "bar" 
 : 
  
 { 
 "x" 
 : 
  
 1 
 , 
  
 "y" 
 : 
  
 2 
 }} 
 

With the transformer, the object is represented as:

  { 
 "bar" 
 : 
  
 "1,2" 
 }