Tipos de parámetros y de datos que se muestra compatibles

En esta página, se enumeran los tipos de datos que puedes usar como tipos de parámetros de API en la ruta o los parámetros de búsqueda para tus métodos de API de backend, además de los tipos que puedes usar como tipos de retorno de método o tipos de cuerpo de solicitud.

Tipos compatibles para parámetros de ruta y búsqueda

Los tipos de ruta y parámetro de búsqueda compatibles son los siguientes:

  • java.lang.String
  • java.lang.Boolean y boolean
  • java.lang.Integer y int
  • java.lang.Long y long
  • java.lang.Float y float
  • java.lang.Double y double
  • java.util.Date
  • com.google.api.server.spi.types.DateAndTime
  • com.google.api.server.spi.types.SimpleDate
  • Cualquier enum
  • Cualquier arreglo o java.util.Collection de los tipos que se enumeran aquí. No se admiten arreglos ni grupos de otros tipos.

Si quieres especificar un parámetro como ruta o parámetro de búsqueda, anota el parámetro con @Named. Por ejemplo:

public Resource get(@Named("id") int id) { … }

Parámetros de ruta

Los parámetros de ruta son parámetros de método incluidos en la propiedad path de la anotación @ApiMethod. Si no se especifica path, todos los parámetros que no tengan la anotación con @Nullable o @DefaultValue se agregarán a la ruta como parámetros de ruta de forma automática. Por ejemplo:

public Resource get(@Named("id") int id) { … }

Para agregar un parámetro a path de forma manual, debes incluir el nombre del parámetro en las marcas {} de la ruta. Los parámetros agregados de forma manual a path no se pueden anotar con @Nullable ni @DefaultValue. Por ejemplo:

@ApiMethod(path = "resources/{id}")
public Resource get(@Named("id") int id) { … }

Parámetros de consulta

Los parámetros de consulta son los parámetros de método no incluidos en la propiedad path de la anotación @ApiMethod. Ten en cuenta que los parámetros opcionales, es decir, los que se anotan con @Nullable o @DefaultValue, nunca se agregan de manera automática a path, por lo que se convierten de forma automática en parámetros de consulta si path no se especifica. Por ejemplo:

public Resource get(@Named("id") @Nullable int id) { … }

Si se especifica path, los parámetros se pueden convertir en parámetros de consulta si no se incluyen en path. Por ejemplo:

@ApiMethod(path = "resources")
public Resource get(@Named("id") int id) { … }

Tipos inyectados

Los tipos inyectados son aquellos tipos que reciben un tratamiento especial a través de Cloud Endpoints Frameworks. Si este tipo se usa como un parámetro de método, no formará parte de la API. En su lugar, Endpoints Framework llenará el parámetro.

Los tipos inyectados son los siguientes:

  • com.google.appengine.api.users.User
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.ServletContext

Tipos de entidad

En la documentación Endpoints Frameworks, los tipos de entidad son sinónimo de Java Beans. Las clases que definas para usar en tu API deben reunir estos requisitos:

  • Tener un constructor público que no contenga argumentos.
  • Controlar el acceso a propiedades privadas con captadores y definidores. Además, cada definidor debe tomar un solo parámetro.

Por lo general, los tipos de entidad también implementan Serializables, pero este no es un requisito para usar Endpoints Frameworks.

No uses la anotación @Named para los parámetros de tipo de entidad.

El cuerpo de la solicitud

Cuando pasas un tipo de entidad como parámetro en un método, las propiedades en el tipo de entidad se asignan a los campos JSON en el cuerpo de la solicitud. Tus métodos deben contener solo un parámetro de tipo de entidad. Por ejemplo:

public Resource set(Resource resource) { … }

Puedes incluir parámetros de tipo de no entidad y un parámetro de tipo de entidad en un método. Por ejemplo:

@ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) { … }

En el ejemplo anterior, las propiedades del parámetro message se asignan a los campos JSON en el cuerpo de la solicitud. La anotación @Nullable indica que el parámetro n es opcional, por lo que se pasa como un parámetro de búsqueda.

El objeto de respuesta

El valor de retorno del método debe ser uno de los siguientes:

  • Un tipo de entidad
  • Un tipo genérico
  • CollectionResponse (com.google.api.server.spi.response.CollectionResponse) o una subclase de CollectionResponse

Los campos JSON del objeto de respuesta se asignan a partir de las propiedades en el valor de retorno.

Efecto de @ApiTransformer en los tipos

Si usas @ApiTransformer, debes tener en cuenta cómo la transformación afecta el tipo.

@ApiTransformer y tipos de parámetros

Cuando se usa un @ApiTransformer, ya sea que el parámetro del método resultante se considere un tipo de parámetro o no depende del resultado de la transformación, no del tipo original. Si un tipo se transforma en un tipo de parámetro, el parámetro de método se considera como un parámetro de API y se debe anotar con @Named.

@ApiTransformer y tipos de entidades

De manera similar, ya sea que el parámetro del método o tipo de datos que se muestra, se considere un tipo de entidad o no depende del resultado de la transformación, no del tipo original. Si un tipo se transforma en un tipo de entidad, el tipo se puede usar como un tipo de datos que se muestra y cuando se usa como un parámetro de método, no se puede anotar con @Named, ya que se considerará como un tipo de entidad.

@ApiTransformer y tipos inyectados

Los tipos inyectados no se ven afectados por un @ApiTransformer. Un parámetro de método solo se considera un tipo inyectado si su tipo original no transformado es un tipo inyectado.