Es habitual que algunos de los parámetros de nuestros servicios sean opcionales para el cliente, lo que provocaría la llega de estos valores en null para nuestra API, lo que puede resultar un problema para algunos parámetros que son requeridos para el correcto funcionamiento del API y que al menos debemos de tener un valor por defecto en caso de no enviarse.

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í.

Mediante la anotación @DefaultValue podemos establecer un valor por default a algunos de nuestros parámetros que son opcionales para el cliente, lo que evita que tengan un valor nulo al llegar al API. Esta característica es especialmente buena en casos en los que el API necesita que estos parámetros tengan algún valor a pesar que el cliente no lo envíe, pues dejarlos en null puede provocar el fallo del servicio.

Imaginemos el siguiente ejemplo, tenemos que construir un servicios de consulta de clientes que permita paginar los resultados, por lo que el servicio deberá proporcionar la página actual y el número de registros esperados por página. En este ejemplo, podríamos imagina que si los valores no se definen, entonces el API debería de retornar todo, pero esto puede provocar un problema de performance, por que hay muchísimos clientes y cada cliente tiene una serie de objetos asociados que deberán ser retornados también, provocando una gran carga sobre la base de datos, es por ello, que debemos asegurarnos de que si el API no recibe estos parámetros entonces deberemos establecer un valor por default. Veamos el siguiente ejemplo:

package api.services;

import java.util.*;
import javax.ws.rs.core.*;

@Path("customers")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class CustomersService {
	
	@GET
	public Response getCustomers(
			@DefaultValue("1") @QueryParam("currentPage") int currentPage, 
			@DefaultValue("10") @QueryParam("pageSize") int pageSize) {
		
		//Validate input
		if(currentPage < 1 || pageSize < 1) {
			return Response.ok("Invalid params").build();
		}
		
		//ccreate Dataset 
		List<String> customers = new ArrayList<>();
		for(int c = 1 ; c<=100 ; c++) {
			customers.add("Customer " + c);
		}
		
		//Calculate sublist range
		int startIndex = (currentPage-1) * pageSize;
		int endIndex = startIndex + pageSize;
		
		//No more results
		if(startIndex >=customers.size()) {
			return Response.ok(new Object[0]).build();
		}
		
		//Prevent ArrayIndexOutOfBoundsException
		if(endIndex > customers.size()) {
			endIndex = customers.size();
		}
		
		//Getting sublist of elements
		List<String> filters = customers.subList(startIndex, endIndex);
		
		return Response.ok(filters)
				.header("x-size", customers.size())
				.header("x-startIndex", startIndex)
				.header("x-endIndex", endIndex)
				.build();
	}	
}

Para este ejemplo hemos definido que si el cliente no envía la página actual (currentPage) le daremos el valor de 1 por default, y para el tamaño de la página (pageSize) hemos definido el valor de 10. Esto quiere decir que en caso de que el cliente no envíe estos parámetros, regresaremos los 10 primeros registros.

También hemos retornado los headers x-size, x-startIndex, x-endIndex como metadato para el cliente, para que sepa el total de los elementos, el index del primer registro y el último respectivamente.

Veamos algunos ejemplos. En primer lugar probaremos ejecutar el servicio sin ninguno de los parámetros, para comprobar los valores por default:

Podemos comprobar que se han retornado los primeros 10 resultados.

Hora probaremos únicamente con el parámetro pageSize=3, lo que establecerá la página por default en 1, regresando los primeros 3 resultados:

Conclusiones

Los valores por default son una excelente opción para lidiar con valores requeridos por el API, pero que nos obligatorios para el cliente, sin embargo, el echo de que tengamos valores por default, no significa que no debemos validar los parámetros, pues el cliente siempre podrá enviar valores no esperados por el API que provoquen una falla o en el peor de los casos, hacer una inyección SQL.

Los bean params hacen referencia a la capacidad de JAX-RS para recibir como parámetro objetos complejos definidos por una clase, esta clase puede ser vista como un Data Transfer Object (DTO), la cual contiene una serie de propiedades recuperadas de varias partes del request, como el header, query, path y formulario.

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í.

Los Beans params no es una característica nativa del protocolo HTTP o la arquitectura REST, si no que JAX-RS la agrega para poder mapear todos los tipos de parámetros en una sola clase, la cual podríamos ver como un DTO que concentra en un solo punto todos los parámetros esperados.

Para comprender mejor como funcionan los Beans params, imaginemos que tenemos un formulario para registrar nuevos clientes, este formulario enviara al servicio todos los campos al API por medio de @FormParams, también enviaremos como un header un token de autenticación, para identificar al usuario que está realizando la invocación, imaginemos que el cliente llego por medio de una campaña promocional, por lo que necesitamos saber si llego por facebook, google, etc. por lo que enviaremos un @QueryParam para saber de donde llego el cliente.

Este caso, podríamos crear un parámetro en Java para uno de los parámetros esperados o podríamos crear una clase como la siguiente:

package api.services;

import javax.ws.rs.*;

public class CustomerDTO {
	@CookieParam("token") 
	private String token;

	@FormParam("firstname") 
	private String firstname; 
	
	@FormParam("lastname") 
	private String lastname;
	
	@FormParam("status") 
	private String status;
	
	@QueryParam("source")
	private String source;

	/* GET and SET */
}

La clase CustomerDTO es en realidad una composición de variables que son recuperadas de varias partes de la petición. Solo en este caso hemos recuperado parámetros de las cookies (@CookieParam), form (@FormParam), query (@QueryParam), sin embargo, la idea de los @BeanParam es que se pueden utilizar cualquiera de las @xxxParam, lo que quiere decir que podemos utilizar:

• @PathParam
• @QueryParam
• @MatrixParam
• @CookieParam
• @HeaderParam

El siguiente paso es crear un método REST que reciba el @BeanParam:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {
	
	@POST
	@Produces(MediaType.APPLICATION_JSON)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(@BeanParam CustomerDTO customer) {
		
		String result = String.format("firstname = %s, lastname = %s, status = %s, token = %s, source = %s", 
				new Object[]{customer.getFirstname(), 
						customer.getLastname(),
						customer.getStatus(), 
						customer.getToken(),
						customer.getSource()});
		
		return Response.ok(result).build();
	}	
}

El formulario con el que invocaremos el servicio REST es el siguiente:

<!DOCTYPE html>
<html>
	<body>
		<p>Customer form</p>
	
		<form action="http://localhost:8080/api-0.0.1-SNAPSHOT/customers?source=google" method="post">
			<div>
				<label for="firstname" style="display:inline-block; width: 100px;">Nombre</label>
				<input id="firstname" type="text" name="firstname" />
			</div>
			<div>
				<label for="lastname" style="display:inline-block; width: 100px;">Apellido</label>
				<input id="lastname" type="text" name="lastname" />
			</div>
			<div>
				<label for="status" style="display:inline-block; width: 100px;">Estatus</label>
				<select id="status" name="status" >
					<option value="active">Activo</option>
  					<option value="inactive">Inactivo</option>
				</select>
			</div>
			<br/>
			<input type="submit" value="Guardar" />
		</form>
	</body>
</html>

Observemos que hemos agregado el query param en el action del <form>, por lo que será enviado al servidor al momento del submit.

Adicional, agregaremos la cookie token directamente desde el inspector de chrome:

Y obtendremos el siguiente resultado:

Conclusiones

Como hemos podido validar, los @BeanParam son una excelente estrategia para realizar una composición de una serie de parámetros en una sola fuente de datos, los cuales podríamos fácilmente reutilizar para más de un servicio. Además, nos evita tener que definir una serie de parámetros para poder recuperar cada uno de los valores esperados.

Las cookies son hasta la fecha una de las formas más utilizadas que tenemos para persistir valores del lado del cliente, las cuales pueden ser recuperadas por el servidor para identificar a un usuario, darle seguimiento o simplemente para guardar algún valor que utilizaremos después.

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í.

Todas las cookies que guardemos en el cliente serán transmitidas al servidor de forma automática al servidor en los request posteriores, lo que puede ser de grán ayuda para identificar la sesión del usuario, el estado o incluso, guardar tokens de autenticación para identificar al usuario en cada llamada.

Las cookies no es algo que podamos ver a simple vista, pues solo se pueden ver con ayuda de herramientas que monitoren el tráfico HTTP, como es el caso del inspector de elementos de Chrome u otras herramientas especializadas como es el caso de Restlet, SOAPUI, postman, etc.

Desde chrome podemos ver todas las cookies que una página ha dejado en nuestro equipo, e incuso, podríamos agregar algunas manualmente para realizar algunas pruebas. Para verlas, solo basta abrir el inspector de elementos, dirigirse a la pestaña de Application y seleccionar la opción de cookies, tal como podemos ver en la siguiente imagen:

Recuperar las Cookies con JAX-RS

Mediante el API de JAX-RS es muy fácil de recuperar las cookies del lado del servidor, ya que solo es necesario anotar con @CookieParam alguno de los parámetros del método Java en la cual queremos inyectar el valor de una cookie. Veamos el siguiente ejemplo que espera una cookie de autenticación llamado token:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {

	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(
			@CookieParam("token") String token) {
		
		if("1234".equals(token)) {
			return Response.ok("OK").build();
		}else {
			return Response.ok("UNAUTHORIZED").status(Response.Status.UNAUTHORIZED).build();
		}
	}
}

En este ejemplo estamos el header token, el cual deberá tener el valor 1234, de lo contrario, mandaremos un error de autenticación.

Establecer una nueva Cookie

Otra cosa que podemos hacer es establecer una nueva cookie en el cliente, por ejemplo, podríamos agregar el token en caso de que este no tenga uno, veamos cómo quedaría:

package api.services;

import java.util.Map;
import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {

	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(
			@CookieParam("token") String token) {
		
		if(token == null) {
			NewCookie newToken = new NewCookie("token", "1234");
			return Response.ok("OK").cookie(newToken).build();
		}
		
		return Response.ok("OK").build();
	}	
}

Utilizamos la clase NewCookie para definir una nueva cookie que deberá ser creada en el cliente, demás, utilizamos el método cookie de la clase Response para enviarla al cliente.

Conclusiones

A pesar de que las cookies han sido la forma tradicional de guardar los datos en el cliente, la llegada de HTML5 nuevas alternativas, como lo es el Local Storage y el Session Storage, de los cuales no hablaremos en esta ocasión, pero las menciono por si quieres investigar un poco más al respecto.

Los header son utilizados en REST para enviar metadatos asociados a la petición o la respuesta, los cuales van desde el formato y tamaño del payload, nombre del servidor del servidor de aplicaciones, fecha de invocación, caducidad de un recurso, versión y nombre del sistema operativo, tipo de navegador, dispositivo, lenguaje y hasta headers para la seguridad.

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í.

Los headers es una sección adicional al payload de una solicitud, la cual no puede ser vista a simple vista, si no que requiere de un analizador HTTP para poderlos ver, sin embargo, todas las solicitudes llevan por default una serie de headers, incluso si nosotros no las establecemos. Los headers enviados por default varían de cliente a cliente y de servidor a servidor, por lo que en este artículo aprenderemos a analizar los headers.

Uno de los principales usos de los header es para enviar los tokens de
autenticación, como es el caso de JSON Web Token (JWT), el cual lo establecemos en el header Authorization, dicho lo anterior, veremos como recuperar este header mediante el API JAX-RS de Java.

package api.services;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("security")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class Security {
	
	@GET
	public Response authenticate(@HeaderParam("authorization") String token) {
		return Response.ok("token="+token).build();
	}
}

Los header pueden ser recuperados anotando los parámetros con @HaderParam, por lo que vamos a requerir un parámetro en Java por cada header que esperamos recibir en el API.

Si ejecutamos el ejemplo anterior, podemos ver el siguiente resultado:

En la parte superior podemos ver los header que definimos en el request y en la parte de abajo los header que nos retorno el servidor; en la respuesta podemos ver el token que le hemos enviado.

Otra de las formas de recuperar los header es por medio de la clase HttpHeaders, la cual podemos inyectar a nuestro método mediante la anotación @Context. La ventaja evidente de esté método es que podemos recuperar cualquier header, sin importar si lo esperábamos o no y nos evita tener que definir una grán cantidad de parámetros si esperamos muchos headers. Veamos un nuevo ejemplo con este método:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("security")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.TEXT_PLAIN)
public class Security {
	
	@GET
	public Response authenticate (@Context HttpHeaders headers) {
		String result = "";
		for(Map.Entry entry: headers.getRequestHeaders().entrySet() ) {
			result += entry.getKey() + "=" + entry.getValue() + ", ";
		}
		
		return Response.ok(result).build();
	}
}

Ahora veamos una ejecución de prueba:

En este caso, podemos observar que hemos recibido muchos más parámetros de los que enviamos, y esto se debe a lo que mencionamos al inicio, y es que cada cliente agrega una serie de headers para identificarlo.

Agregar headres en la respuesta

Ademas de recibir headers, también podemos enviar headers a los clientes del API; los headers los podemos agregar directamente al objeto Response, mediante una serie de claves-valor, veamos un ejemplo:

package api.services;

import java.util.Map;
import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("security")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.TEXT_PLAIN)
public class Security {
		
	@GET
	public Response authenticate (@Context HttpHeaders headers) {
		String result = "";
		for(Map.Entry entry: headers.getRequestHeaders().entrySet() ) {
			result += entry.getKey() + "=" + entry.getValue() + ", ";
		}
		
		Response.ResponseBuilder response = Response.ok(result);
		response.header("my-header1", "value 1");
		response.header("my-header2", "value 2");
		
		return response.build();
	}
}

Conclusiones

No debemos de confundirnos al momento de utilizar los headers, pues no se deben de utilizar como una forma de enviar parámetros a nuestro API, si no como metadatos que complementen el request y que ayuden al servidor/cliente como tratar la solocitud/respuesta.

Una de las cosas que pocos saben, es que REST nos permite crear servicios que se integren a la perfección con los formularios HTML, de tal forma que podemos lugar una etiqueta <form> directamente con un servicio REST. para ello, JAX-RS nos proporciona la anotación @FormParam.

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í.

La diferencia fundamental que tienen los form params con respecto a los demás, es que se obtiene directamente los campo asociados al formulario desde el cual se ejecuta, pero para entender mejor, veamos el siguiente ejemplo:

<html>
	<body>
		<p>Customer form</p>
		<form action="http://localhost:8080/api-0.0.1-SNAPSHOT/customers" method="post">
			<div>
				<label for="firstname" style="display:inline-block; width: 100px;">Nombre</label>
				<input id="firstname" type="text" name="firstname" />
			</div>
			<div>
				<label for="lastname" style="display:inline-block; width: 100px;">Apellido</label>
				<input id="lastname" type="text" name="lastname" />
			</div>
			<div>
				<label for="status" style="display:inline-block; width: 100px;">Estatus</label>
				<select id="status" name="status" >
					<option value="active">Activo</option>
  					<option value="inactive">Inactivo</option>
				</select>
			</div>
			<br/>
			<input type="submit" value="Guardar" />
		</form>
	</body>
</html>

En este ejemplo debemos poner atención en la etiqueta <form>, la cual está apuntando a un servicios REST mediante la etiqueta action, con lo cual le estamos diciendo al navegador que envíe el formulario a nuestro servicio REST.

Otra de las cosas a tomar en cuenta son los campos dentro del form, como lo son el nombre, apellido y estatus, los cuales serán los que sean enviados al servicio REST.

Una vez explicado lo anterior, pasemos a la implementación en JAX-RS para recuperar estos parámetros:

package api.services;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {

	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(
			@FormParam("firstname") String firstname, 
			@FormParam("lastname") String lastname, 
			@FormParam("status") String status) {
		
		String result = String.format("firstname = %s, lastname = %s, status = %s", new String[]{firstname, lastname, status});
		return Response.ok(result).build();
	}
}

Veamos como hemos definido una anotación @FormParam para cada uno de los parámetros esperados del formulario, los cuales serán mapeados a cada uno de los parámetros del método en Java.

Las anotaciones @Consumes la utilizamos definir que esperamos el payload como un formulario.

Probando el servicio

Lo primero será abrir el la página HTML para verlo de la siguiente manera:

Una vez capturado el formulario, la damos grabar, lo que detonará el submit del formulario y la ejecución del servicio REST, lo que dará como resultado lo siguiente:

Podemos ver como el servicio REST ha recibido todos los parámetros y los ha regresado como una cadena de texto.

Mediante la anotación @FormParam es fácil recuperar los valores de un formulario, pues los mapeamos a una parámetro especifico del método Java, sin embargo, esta forma tiene la limitación de que requerimos N parámetros en Java para mapear los N form params, lo que puede llegar a ser complicado en formularios grandes o donde los nombres de los parámetros pudieran variar, en tales casos, podemos implementarlos de la siguiente manera para recuperar todos los form params como un colección:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {
	
	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response getFormDataUsingMultivaluedMap(MultivaluedMap<String, String> formParams) {
		String result = "";
		for(Map.Entry entry: formParams.entrySet() ) {
			result += entry.getKey() + "=" + entry.getValue() + ", ";
		}
		
		return Response.ok(result).build();
	}
}

Conclusiones

Los @FormParam pueden ser una buena alternativa cuando queremos ligar directamente un formulario con servicios REST, evitando tener que construir un request especifico.

Como inconveniente, tenemos que el servicio REST deberá retornar la estructura HTML de la siguiente página que verá el usuario, o en su defecto, podemos redireccionar al usuario a la siguiente página.

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.

Por increíble que parezca, en REST la URL puede proporcionar una de las principales fuentes de información para los servicios, pues es posible definir como parámetros de entrada ciertas parte de la URL, lo que nos permite en primer lugar, crear métodos especiales para atender ciertas URL, pero por otra parte, esos fragmentos de URL pueden ser inyectados como parámetros a los métodos Java.

NOTA: Este artículo pertenece a una guia completa para aprender a crear un API REST con el API de JAX-RS de Java, ve el índice completo aquí.

Hace unos días escribía sobre la forma de escribir los Path y como podemos como podemos podíamos definir parámetros con la anotación @Path, puede regresara a la sección Introducción a las URL con @Path si quieres tener un poco más de contexto sobre lo que estaremos hablando esta sección.

Definiendo un Path Param

No vamos a entrar en mucho detalle sobre como definir un parámetro desde @Path pues ya lo explicamos en una sección pasado, pero si repasaremos como se hacia. 

@GET
@Path("/users/{userId}")
public Response findUserById(long userId) {}

Como podemos apreciar en el fragmento de código anterior, es posible definir ciertas secciones de una URL como parámetros, encerrando entre llaves ({userId}) la parte que queremos recuperar como parámetro desde Java. 

Recuperar una Path Param con @PathParam

Ya que hemos definido todas secciones de parámetros dentro del @Path, lo que seguirá es recuperarlos desde el método Java para poderlos utilizar, para ello, debemos de establecer la anotación @PathParam en cada uno de los parámetros del método Java sobre el cual queremos inyectar el valor.

@GET
@Path("/users/{userId}")
public Response findUserById(@PathParam("userId") long user) {
    System.out.println("UserID ==> " + user);
}

En el fragmento de código anterior, podemos apreciar como hemos establecido la anotación @PathParam para el parámetro user, el cual será inyectado con el valor del parámetro userId del @Path.

Recuperar un Path param mediante UriInfo

La segunda forma de recuperar un Path param es mediante la interface UriInfo, la cual es una interface que contiene todos los metadatos relacionados con la URL. Al ser una interface no puede ser instanciada, por lo que deberá ser inyectada para ser utilizada, vamos como sería:

@GET
@Path("uriInfo/{param1}")
public Response getUriInfo(@Context UriInfo uriInfo) {
    String param1 = uriInfo.getPathParameters().getFirst("param1");
    return Response.ok(param1).build();
}

La interface UriInfo proporciona el método getPathParameters que retorna una subclase de la interface java.util.Map con todos los parámetros, por lo que podemos iterar el nombre de los parámetros y sus valores, o podemos buscar directamente el valor de un parámetro mediante el método getFist. 
Al ejecutar el método anterior deberíamos tener como resultado el valor del parámetro param1, vamos el resultado:

Conclusiones

Los Path params son indispensables para definir de forma clara los recursos de tu API, pues evita tener que agregar parámetros de tipo Query, los cuales hacen que las URL sean complejas y difíciles de recordar, ademas de que no son agradables para SEO.

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í.

El path es conocido como la dirección URL que aparece en la que se encuentra un determinado recurso, por ejemplo, la página de google se encuentra en https://google.com mediante el Método GET, por lo que ninguna otra página podría existir en esa misma URL, porque estaría violando una de las principales reglas de REST. Así como no puede haber otra página en una misma URL, tampoco podría existir, por ejemplo, tener los datos de dos usuarios en la misma URL. Por ejemplo: https://miapi.com/users/1,  está URL nos dice que estamos buscando el usuario con ID = 1, por lo que sin importar que pase, los datos del usuario 1 siempre deberían estar en esa URL.

En JAX-RS, el Path se define como una expresión que se utilizará para identificar hacia qué servicios se debe de direccionar una llamada entrante al API. Para esto, tenemos la anotación @Path  del paquete javax.ws.rs  que nos permite definir la URL en que un determinado método responde. Veamos el siguiente ejemplo:

@GET
@Path("users")
public Response findAllUsers() {
    return Response.ok(userDao.getAllUsers()).build();
}

En este ejemplo, vemos el método findAllUsers  utilizado para obtener todos los usuarios del sistema, lo interesante en este método el valor de la anotación @Path , la cual indica que este servicio estará disponible en la URL /users. Por lo tanto, podríamos ejecutar nuestro servicio en una URL como la siguiente http:<host>:<port>/<app_context>/users.

En este punto el host y el puerto es más que obvio que es, por lo que no entraremos en detalle sobre estos. El <app_context> es la URL base que nos asigna el servidor de aplicación, el cual por lo general corresponde con el nombre del proyecto, y finalmente, el /users está dado por la anotación @Path .

Path Expressions

Con la finalidad de crear servicios para procesar determinadas solicitudes, es necesario crear expresiones que ayuden a JAX-RS a distinguir que método debe de procesar una solicitud determinada, es por ello que @Path  permite definir expresiones complejas, así convertir ciertas secciones de la URL en parámetros que podrán ser utilizados por los métodos para saber cómo procesar la solicitud.

Veamos un ejemplo, imaginemos que tenemos dos usuarios en la base de datos y requerimos poder consultarlos por medio del ID, una solución sería crear dos métodos con diferente URL, por ejemplo:

• @Path(“users/1”)
• @Path(“users/2”)

Los paths anteriores nos permitirían diferencia si queremos consultar el usuario 1 o el 2, sin embargo, esto no es una solución práctica, ya que, si tenemos 100 usuarios, deberíamos de tener 100 métodos con Path diferente, por ello, en lugar de eso, podemos utilizar las expresiones para indicar que ciertas partes de la URL son en realidad un parámetro, veamos el siguiente ejemplo:

@GET
@Path("users/{userId}")
public Response deleteUser( @PathParam("userId") String userId) {
    long parseUserId = Long.parseLong(userId);
    User user = userDAO.findUserById(userId);
    return Response.ok(user.build();
}

Este ejemplo es mucho más sensato, pues ya no hay necesidad de tener un método para cada usuario y en su lugar, hemos definido en el Path la variable {userId} , la cual le indica a JAX-RS, que todo lo que venga después de /users/ deberá ser recuperado y luego inyectado en la variable userId  del método Java. La anotación @PathParam  se utiliza para indicarle a Java en que parámetro debe de inyectar el valor.

A pesar de que este nuevo @Path  funciona, tenemos un detalle, pues le estaríamos diciendo que aceptaría cualquier valor en el parámetro {userId} , pero el ID de los usuarios es numérico, entonces estaríamos a expensas de que nos manden un valor no numérico, y que la instrucción donde parseamos el valor a long  falla, por eso, es necesario protegernos un poco más y complementar la expresión para indicar que el parámetro solo recibe valores numéricos:

@GET
@Path("users/{userId : \\d+}")
public Response findUserById(@PathParam("userId") long userId) {
    System.out.println("userId ==> " + userId);
    List<User> found = this.users.stream().filter(x -> userId == x.getId().longValue()).collect(Collectors.toList());
              
    //Throws error in case of the user not found
    if(found.isEmpty()) return Response.status(Status.BAD_REQUEST).entity("User not found").build();
    User userFound = found.get(0);
    return Response.ok(userFound).build();
}

En este nuevo ejemplo, hemos actualizado el parámetro {userId}  del path para que se vea de la siguiente manera {userId : \\d+} , de esta forma, le indicamos que el parámetro debe de ser uno o más dígitos.

Mediante JAX-RS es posible crear complejas reglas basadas en expresiones regulares para que nuestros parámetros sean los más exactos posibles, sin embargo, no vamos a entrar a detalle sobre este tema, pues podríamos alargarnos muchísimo y mi objetivo es simplemente que sepas que tienes esta posibilidad.

A si como podemos tener una variable, podríamos tener todas las que sean necesarias, por ejemplo, que pasaría si requiere recuperar todos los códigos postales de un país, una ciudad y todas las colonias que hay dentro de un código postal determinado, aquí estaríamos hablando de 3 servicios que podrían estar en conflicto, veamos por qué:

• CP país: /mexico
• CP ciudad: /mexico/cancun
• Colonias por CP: /mexico/cancun/80000

El primero me regresaría todos los códigos postales que están en México, el segundo, me regresaría todos los CP de la ciudad de Cancún, la cual pertenece a México, y finalmente, la tercera me debería indicar todas las colonias que están el CP 80000. El problema con estos Path es que todos comienzan con el País, lo que puede provocar que las URL colapsen, pero por suerte, en JAX-RS es muy simple saltarse este problema, veamos como quedarían los métodos para estos 3 servicios:

@GET
@Path("{country}")
public Response findColonyByCP(
    @PathParam("country") String country) {
}

@GET
@Path("{country}/{city}")
public Response findColonyByCP(
    @PathParam("country") String country,
    @PathParam("city") String city) {
}

@GET
@Path("{country}/{city}/{cp}")
public Response findColonyByCP(
    @PathParam("country") String country,
    @PathParam("city") String city,
    @PathParam("cp") String cp) {
}

Como vemos en este ejemplo, podemos separar cada sección de la URL por medio de variables, y así reconocer cada sección de la URL por separado.

También es posible hacer cosas como la siguiente @Path(“users/{company}-{id}”) , en esta nueva modalidad, tenemos dos parámetros en la misma subsección de la URL, en la cual podemos buscar un usuario de una determinada empresa.

Contexto de los Paths

Hasta este punto hemos visto cómo utilizar la anotación @Path  sobre los métodos, sin embargo, también es posible implementarla a nivel de clase. Cuando un path es definido a nivel de clase, afecta a todos los métodos de la clase, anteponiendo el este path al que definamos en los métodos, por ejemplo, si tenemos una clase que tiene todos los servicios relacionados a usuarios, entonces podríamos definir el @Path(“users”)  a nivel de clase, para que, de este modo, todos los servicios de esta clase inicien con el path /users, veamos un ejemplo:

@Path("/users")
@Consumes(value= MediaType.APPLICATION_JSON)
@Produces(value = MediaType.APPLICATION_JSON)
public class UserService {

    @GET
    public Response findAllUsers() {}
               
    @POST
    public Response createUser(User userRequest) {}

    @PUT
    public Response updateUser(User userRequest) {}
               
    @DELETE
    @Path("{userId}")
    public Response deleteUser( @PathParam("userId") long userId) {}

    @GET
    @Path("{userId : \\d+}")
    public Response findUserById(@PathParam("userId") long userId) {}
}

Lo primero que podemos observar es que varios métodos ya no requieren la anotación @Path , sino solo el método (verb) por el cual responden, por ejemplo, el método findAllUsers  lo podemos ejecutar directamente en la URL GET:/users, por que asume la URL del @Path  de la clase.Por otra parte, el método deleteUsers  estará disponible en la URL /users/{userId}, esto debido a que se concatena el @Path  de la clase con el del método.

Path de la aplicación

Adicional a la anotación @Path  existe otra llamada @ApplicationPath , la cual está un poco fuera de tema, pero vale la pena recordarla. Esta anotación se utiliza definir el Path base que TODA la aplicación tendrá, esta se implementa una clase independiente, por lo general en el paquete base de la app:

package api;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/")
public class RestApplication extends Application {

}

Esta anotación la analizamos en la sección “Creando un API REST en Java” al inicio de este tutorial.

Conclusiones

Como hemos podido constatar, JAX-RS es sumamente flexible a la hora de definir los paths, sin embargo, no hemos abordado aún los QueryParams, PathParams y HeaderParams, los cuales estaremos analizando más a detalle en las siguientes secciones de este tutorial.

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í.

Antes que nada, podrás encontrar todo el código fuente en GitHub: https://github.com/oscarjb1/blog-tutorial-jaxrs/tree/master/HTTP%20method%20extensions/api

Para estos casos, JAX-RS nos ofrece la anotación @HttpMethod  que nos sirve para crear un nuevo método, esta anotación la tendremos que implementar sobre una anotación personalizada. Digamos que requerimos implementar un nuevo método que nos permite bloquear un recurso para que cualquier otro consumidor del API no pueda modificarlo, para esto, podríamos crear un método HTTP llamado LOCK, veamos cómo quedaría:

package api.methods;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import javax.ws.rs.HttpMethod;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("LOCK")
public @interface LOCK {

}

No quiero entrar en los detalles sobre como crear una anotación, pues no es el tema central de este artículo, pues lo que solo nos centraremos en lo que es realmente necesario para crear un nuevo método HTTP. Como vemos, hemos creado una nueva anotación llamada LOCK, esta a su vez, implementa la anotación @HttpMethod , la cual recibe como parámetro el nombre del número método HTTP que vamos a implementar, en este caso “LOCK”.

Finalmente, solo restaría implementar un método que implemente la interface @LOCK :

@LOCK
@Path("{userId}")
@Produces(MediaType.TEXT_PLAIN)
public Response lockUser() {
    return Response.ok("User loked").build();
}

Como vemos, en el método anterior, solo debemos anotar la función con @LOCK  y JAX-RS será lo suficientemente inteligente como para detectar que estamos utilizando el método HTTP LOCK.

Una vez implementado, solo restaría probar que el servicio realmente funciona, para ello utilizamos Restlet para probar el servicio:

Hay que tomar en cuenta que los métodos HTTP predefinidos en JAX-RS nos servirán para prácticamente para el 100% de los casos, por lo que no es recomendable implementar un método HTTP solo por hacerlo. Si bien, no es recomendable crear métodos HTTP solo por crearlo o por tener un método proprio, sí que hay dos casos donde se recomienda crear nuestros propios métodos:

1. Cuando estamos creando alguno protocolo nuevo que requiera de la implementación de nuevos métodos.
2. Cuando alguna aplicación de terceros sobre la cual no tenemos control, nos solicite la creación de un servicio que responda en algún método determinado.

Conclusiones

Hemos visto como JAX-RS es lo bastante extensible para crear fácilmente nuevos métodos HTTP, aun que como ya vimos, debemos ser cuidados al momento de definir un nuevo método, pues crearlo solo por crearlo, puede ser un error que complique nuestra API.

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í.

Entender los métodos HTTP es fundamental para comprender la forma en que funciona la arquitectura REST, pues mediante los métodos le indicamos al servidor la forma en que debe de tratar una determinada petición, dicho esto, una misma URL puede ser tratada de forma diferente por el servidor.

HTTP define una gran cantidad de métodos que son utilizados para diferentes circunstancias, por lo que trataremos de listar lo más relevantes y más utilizamos en la construcción de servicios REST, los métodos son los siguientes:

• GET: Es utilizado únicamente para consultar información al servidor, muy parecidos a realizar un SELECT a la base de datos. No soporta el envío del payload
• POST: Es utilizado para solicitar la creación de un nuevo registro, es decir, algo que no existía previamente, es decir, es equivalente a realizar un INSERT en la base de datos. Soporta el envío del payload.
• PUT: Se utiliza para actualizar por completo un registro existente, es decir, es parecido a realizar un UPDATE a la base de datos. Soporta el envío del payload.
• PATCH: Este método es similar al método PUT, pues permite actualizar un registro existente, sin embargo, este se utiliza cuando actualizar solo un fragmento del registro y no en su totalidad, es equivalente a realizar un UPDATE a la base de datos. Soporta el envío del payload
• DELETE: Este método se utiliza para eliminar un registro existente, es similar a DELETE a la base de datos. No soporta el envío del payload.
• HEAD: Este método se utilizar para obtener información sobre un determinado recurso sin retornar el registro. Este método se utiliza a menudo para probar la validez de los enlaces de hipertexto, la accesibilidad y las modificaciones recientes.

Hasta aquí los métodos más utilizados en la construcción de servicios REST con JAX-RS, sin embargo, existen algunos métodos más que son interesantes conocer, pues no los encontraremos al momento de depurar o analizar el tráfico de red.

• CONNECT: Se utiliza para establecer una comunicación bidireccional con el servidor. En la práctica no es necesario ejecutarlo, si no el mismo API de HTTP se encarga de ejecutarlo para establecer la comunicación previo a lanzar alguna solicitud al servidor.
• OPTIONS: Este método es utilizado para describir las opciones de comunicación para el recurso de destino. Es muy utilizado con CORS (Cross-Origin Resource Sharing) para validar si el servidor acepta peticiones de diferentes origines.

A pesar de que los métodos están diseñados para realizar ciertas acciones, la realidad es que nada impide que los utilices de forma errónea, es decir, fácilmente podrías utilizar el método DELETE para consultar o el POST para eliminar un recurso, si bien, el API funcionará, el desarrollador se volverá loco al intentar entender como funciona el API, es por este motivo que debemos entender y tener mucho cuidado en la forma en que implementamos los métodos.

A pesar de que existe una gran cantidad de método HTTP, la implementación de JAX-RS solo implementa los que son realmente utilizados para crear servicios REST. Para implementar un método HTTP con JAX-RS solo es necesario anotar un método con cualquiera de las siguientes anotaciones del paquete javax.ws.rs :

• @GET
• @POST
• @PUT
• @DELETE
• @HEAD
• @OPTION

Por ejemplo, para crear un servicio que retorne todos los Usuarios, podríamos crear un método como el siguiente:

@GET
public Response findAllUsers() {
    List<Users> users = userDAO.getUsers();
    return Response.ok(users ).build();
}

Antes de comenzar, te cuento que puedes descargar el código completo en https://github.com/oscarjb1/blog-tutorial-jaxrs/tree/master/M%C3%A9todos%20HTTP/api

De la misma forma, podríamos crear cualquier otro método y anotarlo con el método que necesitemos. Para comprobar cómo funcionan los métodos, vamos a crear un servicio REST que nos permite tener las operaciones básicas para realizar un CRUD (Altas, Bajas, Cambio, Consulta en inglés).

package api.services;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.HEAD;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;

import api.domain.User;


@Path("/users")
@Consumes(value= MediaType.APPLICATION_JSON)
@Produces(value = MediaType.APPLICATION_JSON)
public class UserService {
	
	//User database pre-initialization
	private static final List<User> users = new ArrayList<>();
	
	static {
		users.add(new User(1L, "oscar", "1234"));
		users.add(new User(2L, "juan", "1234"));
		users.add(new User(3L, "maria", "1234"));
	}
	
	
	@GET
	public Response findAllUsers() {
		return Response.ok(this.users).build();
	}
	
	@POST
	public Response createUser(User userRequest) {
		userRequest.setId(users.size()+1l);
		this.users.add(userRequest);
		return Response.ok(userRequest).build();
	}
	
	@PUT
	public Response updateUser(User userRequest) {
		List<User> found = this.users.stream().filter(
                    x -> userRequest.getId() == x.getId()).collect(Collectors.toList());
		
		//Throws error in case of the user not found
		if(found.isEmpty()) 
                    return Response.status(Status.BAD_REQUEST).entity("User not found").build();
		
		User updateUser = found.get(0);
		updateUser.setPassword(userRequest.getPassword());
		updateUser.setUsername(userRequest.getUsername());
		return Response.ok(updateUser).build();
	}
	
	@DELETE
	@Path("{userId}")
	public Response deleteUser( @PathParam("userId") long userId) {
		System.out.println("userId ==> " + userId);
		List<User> found = this.users.stream().filter(
                    x -> userId == x.getId().longValue()).collect(Collectors.toList());
		
		//Throws error in case of the user not found
		if(found.isEmpty()) 
                    return Response.status(Status.BAD_REQUEST).entity("User not found").build();
		
		User updateUser = found.get(0);
		this.users.remove(updateUser);
		return Response.noContent().build();
	}
	
	
	@HEAD
	public Response pingUsersService() {
		return Response.noContent().header("running", true).build();
	}
	
}

Como podrás apreciar, no estamos utilizando una base de datos real para guardar los cambios, pues no es el propósito en este punto, más bien, queremos enfocarnos en la forma en que los métodos son declarados, dicho esto, pasemos a analizar cómo funciona:

Inicialización del servicio

En primer lugar, podemos apreciar que el servicio responde en el path /users, lo cual podemos comprobar en la anotación @Path  a nivel de clase. Por el momento no profundizaremos en esto, pues más adelante tendremos una sección especial para explicar cómo funcionan los paths. Por otra parte, tenemos una lista llamada users, la cual utilizaremos como un sustituto a la DB para ir guardando los nuevos usuarios, actualizar o borrar los existentes. De entrada, iniciamos la lista con 3 usuarios.

Las anotaciones @Consumes  y @Produces  las utilizamos para indicar que él payload recibido y enviado como respuesta serán en formato JSON respectivamente. En otra sección de esta guía profundizaremos en el tema, por lo que por ahora no es necesario entender del todo esta parte.

Consulta de todos los usuarios (@GET)

El método findAllUsers es utilizado fue desarrollado para retornar todos los usuarios que tengamos registrados. Como ya hablamos anteriormente, de inicio tendremos 3 usuarios precargados, por lo que podremos comprobar si realmente funciona. Para la prueba utilizaremos el plugin de Chrome llamado Restlet, pero podrías utilizar otros programas como SOAPUI.

En la imagen podemos apreciar claramente que, al ejecutar el servicio, este nos regresa un array con los 3 usuarios que se pre-cargaron.

Crear un nuevo usuario (@POST)

De la misma forma en la que consultamos los usuarios existentes, podemos crear nuevos mediante el método POST. La única diferencia, es que es necesario enviarle en el payload el username  y el password  con el que se deberá crear, el ID será auto generado.

Como resultado de la ejecución, tenemos un nuevo usuario creado, podemos comprobar que es nuevo por el ID que se va generando de forma secuencial.

Actualización de un usuario existente (@PUT)

De la misma forma en que acabamos de crear un usuario, podemos actualizar sus datos mediante el método PUT. Para comprobar de que el usuario es actualizado, podremos observar que el ID del mismo no cambiara, y en su lugar, solo se actualizara el username  y el password . Como vamos a actualizar el registro, es necesario enviarle el ID como parámetro.

Eliminar un usuario (@DELETE)

El caso del delete es un poco diferente, pues como este método no soporta enviarle el payload, es necesario enviarle el ID del usuario a eliminar de otra forma. En este caso, vamos a enviarle el ID como parte de la URL, es por ello, que agregaremos “/1” al final y agregaremos la anotación @PathParam  para indicarle a JAX-RS como debe de recuperar el ID. Más adelante en otra sección de este tutorial analizaremos cómo funcionan estos parámetros, por ahora no nos preocupemos por esto.

En este caso no hay necesidad de retornar nada, es por ello que vemos el mensaje de “NO CONTENT”.

Comprobar disponibilidad del servicio (@HEAD)

Finalmente, validaremos si el servicio está activo realizando una petición HEAD, el cual nos regresará el header “running” si está actualmente en funcionamiento.

Conclusiones

Como hemos podido comprobar, crear servicios REST que respondan en los diferentes métodos es sumamente simple, y solo falta anotar el método con la anotación adecuada para crear un nuevo servicio. Solo quedo pendiente comprobar el funcionamiento del método OPTION (@OPTION ) el cual tu podrías implementar como tarea.