Publicación con representación JSON y XML en JAX-RS

Hace poco tiempo hice una presentación de REST en la empresa en la que trabajo. El objetivo de la presentación era mostrar una implementación de REST por medio del API JAX-RS.

Durante la presentación hicimos un pequeño ejemplo con las tecnologías: Jax-RS + Maven + GlassFish + Jersey la cual comparto.

Creacion de proyecto web.

Partiremos de un proyecto web vacío e iremos incorporando las dependencias requeridas para la creación del servicio REST.

Vamos a colocarnos en el directorio en el que crearemos nuestro proyecto y ejecutaremos el siguiente comando de maven:

mvn archetype:generate -DgroupId=mx.org.miempresa.miservicio -DartifactId=MiServicio -DarchetypeArtifactId=maven-archetype-webapp

En version colocar 1.0-SNAPSHOT
Teclear "Y" + enter

Agregar dependencia de JAX-RS

Ahora necesitamos declarar la dependencia de JAX-RS Puesto que usaremos GlassFish no necesitamos empaquetar nada con nuestra aplicación. El servidor ya tiene todo incluido.

<dependency> 
  <groupId>javax.ws.rs</groupId> 
  <artifactId>javax.ws.rs-api</artifactId> 
  <version>2.0</version> 
  <scope>provided</scope> 
</dependency>

JAX-RS Annotations. JAX-RS utiliza anotaciones para indicar los recursos, verbos, filtros, interceptores, parámetros, ..., utilizados en REST. La siguiente lista presenta algunas de las anotaciones utilizadas dentro del API. Para consulta de la lista de anotaciones disponibles consultar la pagína de Jersey.

• @Path. Etiqueta para identificar un recurso que nos interesa publicar.
• @Produces. Especifica el tipo de MIME que el recurso produce y envía al cliente.
• @Consumes. Especifica el tipo de MIME que el recurso consume y que es recibido del cliente.
• @Provider. Utilizado para cualquier cosa de interés para JAX-RS como MessageBodyReader y MessageBodyWriter.

Request Method Designators. </ br>Para indicar los verbos HTTP a utilizar, JAX-RS proporciona las siguientes anotaciones:

• @Get. Http GET requests.
• @PUT. Http PUT requests.
• @POST. Http POST requests.
• @DELETE. Http DELETE requests.
• @HEAD. Http HEAD requests.

Extrayendo parámetros Con JAX-RS podemos extraer los siguientes tipos de parámetros de un recurso:

1. Query. Este parámetro se extrae mediante la anotación @QueryParam. Si queremos un valor por default cuando el parámetro no es enviado, podemos utilizar la anotación @DefaultValue.
2. URI path. Este parámetro se extrae mediante la anotación @PathParam.
3. Form. Extrae la información del request con representación de tipo MIME "application/x-www-form-urlencoded" por medio de la anotación @FormParam

@POST
@Consumes("application/x-www-form-urlencoded")
public void post(@FormParam("name") String name) {
    // Store the message
}

4. Cookie. Permite extraer información de los cookies declarados por medio de la anotación @CookieParam.
5. Header. Permite extraer información de los headers por medio de la anotación @HeaderParam.
6. Matrix.Permite extraer información de los segmentos de la URL. Los parametros matrix son un conjunto de llave=valor. por ejemplo: /libros/2014;autor=clerks En la URL anterior, el parámetro matrix es autor=clerks separado por un ';'

Creación del recurso Como primer ejemplo haremos un recurso con el verbo GET.
Vamos a crear la siguiente clase en el paquete mx.org.miempresa.miservicio.entities:

@Path("pagos/{idCliente}")
public class PagoResource {
    @GET
    @Produces("application/json")
    public String getPagoById(@PathParam("idCliente") int idCliente) 
    {
         return "{\"cantidad\":520,\"idCliente\":23}";
    }
}

Registro del recurso
Para que nuestro recurso sea visible, será necesario indicar su existencia por medio de la implementación de la clase Application. Vamos a crear una clase llamada MiServicioApplication en el paquete mx.org.miempresa.miservicio.

@ApplicationPath("/")
public class MiServicioApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> el = new HashSet<Class<?>>();
        el.add(PagoResource.class);
        return el;
    }
}

Compilación y empaquetamiento del recurso
Ahora necesitamos el WAR para desplegarlo en nuestro servidor. Para generar el war iremos al directorio de nuestra aplicación y ejecutaremos el siguiente comando de maven:

mvn clean package

Despliegue del servicio
Es hora de desplegar nuestro recurso. Para poder desplegar nuestro recurso realizamos los siguentes pasos:

1. Iniciar el servidor de glassfish.
2. Abrir un navegador y teclear la siguiente dirección: localhost:puerto
3. Click en aplicaciones
4. Click en desplegar
5. Click en seleccionar archivo
6. Seleccionar el war recien creado
7. Click en ok

Prueba de consumo del recurso
CURL es una herramienta de línea de comandos para transferir datos con sintaxis URL. Para probar el consumo de nuestro recurso instalaremos esta herramienta.
Una vez instalada ejecutamos el siguiente comando:

curl http://host:port/context/pagos/2

Donde context corresponde al nomnbre asignado al campo "context root" solicitado por glassFish al desplegar el servicio. Por ejemplo yo invoco el siguiente comando: http://cmoralesflap:8080/coco/pagos/2

Por último dejo los comandos para los demás verbos de HTTP con CURL:

GET

curl http://host:port/context/pagos/2

POST

curl –X POST -d "data" URI
curl -H "Accept: application/json" -H "Content-Type: application/json" -d '{\"cantidad\":520,\"idCliente\":23}' http://host:port/context/pagos/2

PUT

curl -X PUT -d "data" URI

DELETE

curl -X DELETE URI

Algunos parámetros útiles:

-i. Shows response header

-H. Pass request headers to the resource

-H "Accept: application/json“

-H "Content-Type: application/json"

-X. Pass a HTTP method name

d. Pass parameters enclosed in quotes. Multiple parameters are separated by ‘&’

En la siguiente entrada publicaremos un recurso mediante POST y haremos uso de la serialización con JSON y XML para la negociación de la representación.