Query params con @QueryParam

Otra de las formas que tenemos para enviar parámetros al API REST son los Query Params, los cuales son una serie de clave-valor que se agregan al final de la URL, justo después del signo de interrogación (?).

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Para comprender mejor que es un Query param a analizar la siguiente URL para consultar los clientes por medio del nombre:

http://myapi.com/customers?name=oscar

El query param es la clave valor name=oscar que vemos al final de la URL, y como regla, siempre deberán estar después del símbolo de interrogación. Además, una URL puede tener N query params, cómo el siguiente ejemplo:

http://myapi.com/customers?firstname=oscar&lastname=blancarte&status=active

Esta URL la podemos utilizar para buscar a todos los clientes donde su nombre es oscar, su apellido es blancarte y su estatus es activo. Cuando utilizamos más de un Query param, es importante separar cada uno mediante el simbolo &.

Recuperar los Query params con JAX-RS

Una vez explicado lo anterior, vamos a pasar a explicar como podemos recuperar los query params mediante el API JAX-RS de Java.

La forma más simple de recuperar un Query param es anotar los parámetros de los métodos con @QueryParam, de tal forma que deberemos tener un parámetro por cada query param esperado. Veamos el siguiente ejemplo:

@GET
@Path("customers")
public Response getCustomers(
		@QueryParam("firstname") String firstname, 
		@QueryParam("lastname") String lastname, 
		@QueryParam("status") String status) {
	String result = String.format("firstname = %s, lastname = %s, status = %s", new String[]{firstname, lastname, status});
	return Response.ok(result).build();
}

Podemos observar que hemos definido la anotación @QueryParam en cada parámetro sobre el cual queremos mapear el parámetro.

Veamos ahora un ejemplo del ejecución de este método:

Como resultado podemos ver que hemos recibido los parámetros desde Java y devueltos como parte de la respuesta, lo que demuestra que hemos logrado mapear los query params con los parámetros del método Java.

El ejemplo anterior es la forma más simple de recuperar los query params, sin embargo, tiene el inconveniente de que debemos definir un parámetro en Java para cada query param que esperamos recibir, lo que puede ser complicado si tenemos muchos o los nombre de los query params pueden variar, pues no tendremos forma de predecirlos para mapearlos a un parámetro en Java.

Para solucionar estos casos tenemos la clase UriInfo, la cual debemos de inyectar al método en lugar de los @QueryParam, veamos el siguiente ejemplo:

@GET
@Path("customers2")
public Response getCustomers(
		@Context UriInfo uriInfo) {
	String result = "";
	for(Map.Entry entry: uriInfo.getQueryParameters().entrySet() ) {
		result += entry.getKey() + "=" + entry.getValue() + ", ";
	}
	return Response.ok(result).build();
}

En este nuevo ejemplo podemos apreciar que hemos inyectado la clase UriInfo mediante la anotación @Context y por medio de esta clase podemos recuperar todos los query params, sin importar la cantidad que nos envíen e incluso si lo esperamos o no. La ventaja de este método es que podemos recuperar todos los query params como un Set e iterar todos los query params enviados.

Observemos en esta última prueba que hemos enviado los query params de siempre y hemos agregado el param date.

Conclusiones

Hemos comprobado lo fácil que es recuperar los query params con @QueryParam, he incluso, recuperarlos mediante la clase UriInfo, pero hay que tener cuidado al momento de utilizarlos, pues en muchos de los casos, podríamos pasar los parámetros mediante @PathParam.

Por lo general, los @QueryParam se utilizan para complementar las búsquedas y los @PathParam para establecer el contexto de la búsqueda, es decir, mediante @PathParam decimos lo que estamos buscando y los @QueryParam como los queremos o los filtros de la selección.