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.

The post Valores por defecto con @DefaultValue appeared first on Oscar Blancarte - Software Architecture.

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.

The post Bean Params con @BeanParam appeared first on Oscar Blancarte - Software Architecture.

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.

The post Cookie params con @CookieParam appeared first on Oscar Blancarte - Software Architecture.

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.

The post Header params con @HeaderParam appeared first on Oscar Blancarte - Software Architecture.

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.

The post Path params con @FormParam appeared first on Oscar Blancarte - Software Architecture.

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.

The post Query params con @QueryParam appeared first on Oscar Blancarte - Software Architecture.

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.

The post Entendiendo los métodos HTTP (JAX-RS) appeared first on Oscar Blancarte - Software Architecture.

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.

The post Métodos HTTP (REST) appeared first on Oscar Blancarte - Software Architecture.

Sin lugar a duda, los servicios REST ya se han convertido en la principal tecnología para construir servicios, superando con creces a los servicios SOAP o comúnmente conocidos como Web Services. A pesar de que REST ya es visiblemente la tendencia en el desarrollo de servicios, sigue existiendo una gran discusión acerca de si SOAP es mejor que REST o al revés, sin embargo, no quiera tocar este tema ahora, pues no es el tema central de este artículo, para eso he creado el artículo “SOA vs REST” donde discutimos sobre estas dos tecnologías y sus ventajas y desventajas.

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

Configurando el proyecto

Dicho este, pasemos ahora si a implementar un API REST con Java, para esto, será indispensable crear un proyecto de tipo WEB en tu IDE favorito, en este caso, vamos a crear un “Dynamic web project” en Eclipse, para esto nos dirigimos a file -> new -> Other en el menú superior:

Seleccionamos la opción Dynamic web Project y presionamos Next para iniciar con la configuración de la aplicación:

Una vez aquí, escribimos “api” como nombre del proyecto y seleccionamos nuestro servidor de aplicaciones de preferencia, en nuestro caso, utilizamos Wildfly 11 pero podrías utilizar cualquier otro que tengas disponible. Finalmente, presionamos “Finish” para concluir con la creación del proyecto. El siguiente paso será convertir nuestro proyecto a un proyecto Maven, con la finalidad de administrar más fácilmente nuestras librerías. Para ello, nos posicionaremos sobre el proyecto creado y presionaremos “click derecho“ para abrir las opciones del proyecto, estando allí, nos dirigimos a configure -> convert to Maven Project, tras presionar esto, saldrá una ventana para configurar el proyecto, a lo que simplemente daremos finalizar.

Tras realizar los pasos anteriores deberás ver el proyecto tal y como se ve en la imagen anterior. Podrás observar una pequeña “M” en el ícono del proyecto, señal de que se trata de un proyecto Maven.

El siguiente paso es configurar las librerías de JavaEE y Wildfly con la finalidad de que estén disponibles en nuestro proyecto, por lo que tendremos que ir al archivo pom.xml y agregar las siguientes dos librerías:

<dependency> 
    <groupId>javax</groupId> 
    <artifactId>javaee-api</artifactId> 
    <version>7.0</version> 
    <scope>provided</scope> 
    <type>jar</type> 
</dependency> 
<dependency> 
    <groupId>org.wildfly.core</groupId> 
    <artifactId>wildfly-server</artifactId> 
    <version>2.2.0.Final</version> 
    <scope>provided</scope> 
</dependency>

Guardamos los cambios y tendremos que esperar un momento hasta que Eclipse descarga todas las dependencias necesarias, para esto, verás un indicador de progreso en la parte inferior derecha de Eclipse. Una vez que ha finalizado, estamos listos para empezar a desarrollar.

Iniciando el desarrollo

Lo primero que debemos de hacer para iniciar nuestra API REST es indicarle el Path base desde el cual estará respondiendo nuestra API. Este path corresponde a la URL a partir de la cual se expondrá nuestros servicios. Para lograr esto, será necesario crear una clase que extienda de “Application”, esta clase puede llamarse como sea y puede colocarse en cualquier paquete, lo único importante es que extienda de Application y defina la anotación @ApplicationPath. En nuestro caso crearemos la clase RestApplication en el package api.

package api; 

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

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

Como podemos ver, hemos definido “/” como URL base, es decir que los servicios responderán a partir de la raíz del proyecto, pero tu podrías remplazarla por la URL base que más te guste, como por ejemplo “/api” o “/services”.

El siguiente paso será crear nuestro primer servicio, para lo cual deberemos crear una nueva clase, en este caso, crearemos la clase HelloWorldRest en el mismo paquete:

package api; 
import javax.ws.rs.Consumes; 
import javax.ws.rs.GET; 
import javax.ws.rs.Path; 
import javax.ws.rs.Produces; 
import javax.ws.rs.core.MediaType; 
import javax.ws.rs.core.Response; 

@Path("/helloworld") 
@Produces(MediaType.APPLICATION_JSON) 
@Consumes(MediaType.APPLICATION_JSON) 
public class HelloWorldRest {               

    @GET  
    public Response sayHello() {     
        return Response.ok("Hello World desde el API REST",MediaType.APPLICATION_JSON).build();   
    } 
}

Como podrás observar, esta es una clase común y corriente pero que tiene algunas anotaciones, las cuales serán reconocidas por el servidor de aplicaciones para finalmente exponer el servicio, analicemos para que esta cada una de ellas.

La anotación @Path indica la URL en la cual responderá este servicio, cabe mencionar que esta anotación se puede poner a nivel de clase y método, en este caso, al estar a nivel de clase, afecta a todos los servicios que definamos, pero eso lo vamos a analizar más adelante.

Las siguientes dos anotaciones son para indicar que tipo de mensaje esperamos como entrada (consumes) y que tipo de mensaje vamos a responder (produces). En este caso, estamos indicando que esperamos JSON como entrada y que vamos a responder igualmente con JSON.

Finalmente, siguen los métodos, una clase puede tener más de un método, y cada método se puede exponer como un servicio independiente, sin embargo, en esta primera introducción empezaremos con uno. La anotación @GET le indica al servidor de aplicaciones que el método responde por el método GET únicamente. Adicional tenemos anotaciones para los demás métodos, como @POST, @PUT, @DELETE, etc. pero estos los estaremos analizando más adelante.

Podrás observar que el método responde con un tipo llamado Response, esta es una clase de utilidad que nos proporciona el API de JAX-RS para convertir fácilmente un objeto en un JSON en nuestro caso. Esta clase nos proporciona el método ok, el cual nos crea una respuesta con status 200, es decir, respuesta exitosa, la cual recibe el mensaje que queremos responder y el tipo de datos del mensaje, en nuestro caso JSON.

Probando nuestro Hello World

En este punto hemos terminado nuestro primer servicio, por lo que solo resta desplegarlo y probarlo. Para desplegarlo, basta con presionar el click derecho sobre el proyecto y presionar Run As -> Run on Server, presionar siguiente y finalizar.

Si la aplicación desplego correctamente, podremos probar el servicio en la URL http://localhost:8080/api-0.0.1-SNAPSHOT/helloworld, esta URL la podrás ejecutar directamente sobre el navegador:

En este punto te estarás preguntando como es que se generó esta URL, por lo que explico a continuación:

La URL se forma con la siguiente formula: <server_path>:<port>/<app_context>/<app_path>/<service_path>

La sección <server_path> y <port> corresponde al host del servidor y el puerto en el cual responde, esto corresponde a Wildfly.

La sección <app_context> corresponde a la URL base que nos asigna el servidor de aplicaciones cuando desplegamos.

La sección <app_path> fue la que definimos en la anotación @ApplicationPath. En nuestro caso, al definirla como “/” quiere decir que responderá a partir de la raíz del proyecto.

Finalmente, <service_path> corresponde a la URL definida en la anotación @Path, la cual se definió como “helloworld”.

Conclusiones

Hasta este punto hemos aprendido a crear un proyecto web y configurarlo para que responda a nuestras solicitudes como un API REST, por lo que en la siguiente sección de esta guía aprenderemos a utilizar los demás métodos (POST, DELETE, PUT) y aprenderemos a configurar nuestras URL para responder a URL más complejas, por lo que te invito a que te suscribas a mi blog para hacerte llegar las actualizaciones.

The post Creando un API REST en Java (parte 1) appeared first on Oscar Blancarte - Software Architecture.