Entendiendo los métodos HTTP (JAX-RS)

En la entrada pasada hablamos acerca de los métodos HTTP disponibles por JAX-RS, sin embargo, hay ocasiones en las que los métodos implementados por default no son suficientes y necesitamos agregar alguno adicional.

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.