This page lists the data types you can use as API parameter types in the path or query parameters for your a backend API methods, and the types you can use as method return types or request body types.
API parameters must always be annotated with
@Named
.
For example:
public Resource get(@Named("id") int id) { … }
Supported parameter types
The supported parameter types are the following:
- java.lang.String
- java.lang.Boolean and boolean
- java.lang.Integer and int
- java.lang.Long and long
- java.lang.Float and float
- java.lang.Double and double
- java.util.Date
- com.google.api.server.spi.types.DateAndTime
- com.google.api.server.spi.types.SimpleDate
- Any enum
- Any array or java.util.Collection of a parameter type
Path parameters
Path parameters are the method parameters included in the
path
property of the
@ApiMethod
annotation. If
path
is unspecified, any parameters not annotated
with
@Nullable
or
@DefaultValue
will be automatically added to the path (they will be path
parameters). For example:
public Resource get(@Named("id") int id) { … }
To manually add a parameter to
path
, include the parameter name in
{}
marks
in the path. Parameters manually added to
path
cannot be annotated with
@Nullable
or
@DefaultValue
. For example:
@ApiMethod(path = "resources/{id}")
public Resource get(@Named("id") int id) { … }
Query parameters
Query parameters are the method parameters not included in the
path
property
of the
@ApiMethod
annotation. Note that optional parameters, namely, those
annotated with
@Nullable
or
@DefaultValue
, are never automatically added to
path
, so they are automatically query parameters if no
path
is specified.
For example:
public Resource get(@Named("id") @Nullable int id) { … }
If
path
is specified, parameters can be made query parameters by not including
them in the
path
. For example:
@ApiMethod(path = "resources")
public Resource get(@Named("id") int id) { … }
Injected types
Injected types are those types that receive special treatment by the Endpoints framework. If such a type is used as a method parameter, it will not be made a part of the API. Instead, the parameter will be filled in by the framework.
The injected types are the following:
- com.google.appengine.api.users.User
- javax.servlet.http.HttpServletRequest
- javax.servlet.ServletContext
Entity types
Entity types are those types that are available as method return types or as the request body of an API request. Entity types are generally used for resources in a REST API. Any type except a parameter or injected type is considered an entity type. Entity types cannot be annotated with @Named, and as an API request can only have one body, there can only be a single entity parameter per method. For example:
public Resource set(Resource resource) { … }
Effect of API Transformers on Types
If you use API transformers , you'll need to be aware of how the type is impacted by the transformation.
API Transformers and parameter types
When an API transformer is used, whether or not the resulting method parameter
is considered a
parameter type
depends on the result of transformation,
not on the original type
. If a type is transformed to a parameter type, the
method parameter will be considered an API parameter and must be annotated with
@Named
.
API Transformers and entity types
Similarly, whether or not a method parameter or return type
is considered an
entity type
depends on the result of transformation, not on
the original type. If a type is transformed to an entity type, the type can be
used as a return type, and when used as a method parameter, it cannot be annotated
with
@Named
as it will be considered an entity type.
API Transformers and injected types
Injected types are not affected by API transformers. A method parameter is only considered an injected type if its original non-transformed type is an injected type.