Crear servicios REST en Java en 10 minutos

Esta es una guía practica para crear un par de servicios RESTful, si deseas conocer los conceptos teóricos de este estilo de arquitectura te recomiendo leer los siguientes enlaces.

API Rest ¿Que es? y sus ventajas

Aspectos básicos de RESTful

Introduccion a RESTful

Por allá en el 2013 tuve un tímido acercamiento a la plataforma Java EE, todavía era una plataforma compleja. Para implementar unos servicios REST era necesario implementar interfaces, extender clases abstractas y configurar archivos XML. La plataforma ha evolucionado con el tiempo para bien, haciendo más facil el desarrollo de los servicios REST gracias a las anotaciones las cuales reemplazan las configuraciones de archivos XML. Gracias a estas mejoras podemos crear un par de servicios REST en 10 minutos o menos. Vamos a por ello!!

Requerimientos

Java 8

Wildfly 12

Netbeans 8.2 con Maven y soporte para Java EE

Presentación de los servicios a crear

Vamos a crear dos servicios, uno para persistir la información de una persona y otro para consultar la información de una persona. En ambos servicios usaremos JSon para representar los datos de una persona.

1.- Crear el proyecto web demo-rest

Nuevo Projecto → Maven → Web Application

En project name ingresar demo-rest

En package ingresar demo.rest

2.- Creamos la clase Persona para encapsular los datos de un objeto persona

/* * To change this license header, choose License Headers in Project Properties. * To change this template file, choose Tools | Templates * and open the template in the editor. */ package demo.rest.domain; import java.io.Serializable; /** * * @author Roberto Lopez */ public class Persona implements Serializable { private String name; private String lastname; private int age; public Persona(){ name = ""; lastname = ""; age = 0; } /** * @return the name */ public String getName() { return name; } /** * @param name the name to set */ public void setName(String name) { this.name = name; } /** * @return the lastname */ public String getLastname() { return lastname; } /** * @param lastname the lastname to set */ public void setLastname(String lastname) { this.lastname = lastname; } /** * @return the age */ public int getAge() { return age; } /** * @param age the age to set */ public void setAge(int age) { this.age = age; } @Override public String toString(){ return "[name=" + name + ", lastname=" + lastname+ "]"; } }

1. La clase Persona implementa a la interface Serializable
2. La clase Persona tiene un constructor sin parametros

3.- Creamos la clase de los servicios POST y GET para el recurso Persona

/* * To change this license header, choose License Headers in Project Properties. * To change this template file, choose Tools | Templates * and open the template in the editor. */ package demo.rest.domain; import java.net.URI; import java.util.HashMap; import java.util.Map; import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.core.Context; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; import javax.ws.rs.core.UriInfo; /** * * @author Roberto Lopez */ @Path("/persona") public class PersonaRestService { private static final Map<Integer, Persona> personasMap = new HashMap<>(); @Context private UriInfo uriInfo; public PersonaRestService(){ System.out.println("creando una instancia de PersonaRestService"); } @POST @Consumes(MediaType.APPLICATION_JSON) public Response addPersona(Persona persona) { System.out.println("addPersona(" + persona +")"); Integer id = (personasMap.size() + 1); personasMap.put(id, persona); URI uri = uriInfo.getAbsolutePathBuilder().path(id.toString()).build(); return Response.created(uri).build(); } @GET @Path("/{id}") @Produces(MediaType.APPLICATION_JSON) public Persona getPersona(@PathParam("id") Integer id){ if(!personasMap.containsKey(id)){ return null; } return personasMap.get(id); } }

Como podrás observar, esta es una clase común y corriente pero que tiene algunas anotaciones propias para el soporte de REST javax.ws.rs.*, 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.

La anotación @Context permite inyectar un objeto de la clase UriInfo
Las anotaciones @Consumes y @Produces 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. La plataforma REST se encargar de parsear el mensaje JSon a objeto y viceversa.

La anotación @POST indica que nuestro método addPersona va a procesar las peticiones POST y la anotación @GET inicia que nuestro método getPersona va a procesar las peticiones GET.
El método getPersona devuelve la información de una persona en formato JSon
La anotación @Path("/{id}") y @PathParam("id") están relacionadas, nos permite obtener el id de la URL como un parámetro para nuestro método getPersona

4.- Extendemos la clase Abstracta ApplicationInfo

/* * To change this license header, choose License Headers in Project Properties. * To change this template file, choose Tools | Templates * and open the template in the editor. */ package demo.rest.domain; import java.util.Set; import javax.ws.rs.core.Application; /** * * @author Roberto Lopez */ @javax.ws.rs.ApplicationPath("rest") public class ApplicationConfig extends Application { @Override public Set<Class<?>> getClasses() { Set<Class<?>> resources = new java.util.HashSet<>(); resources.add(demo.rest.domain.PersonaRestService.class); return resources; } }

Debemos extender la clase javax.ws.rs.core.Application para registrar nuestra clase que implementa nuestros servicios REST.
Observar que esta clase también tiene la anotación @javax.ws.rs.ApplicationPath("rest") donde rest formará parte de la URL http://localhost:8080/demo-rest-1.0-SNAPSHOT/rest/persona de nuestro servicio.

5.- Clean and Build
Hacemos un Clean Build y Ejecutamos. Netbeans se encarga de desplegar nuestra aplicación web e iniciar el servidor WildFly

6.- Probar los servicios
Para probar nuestros servicios yo utilizo RestClient https://github.com/wiztools/rest-client/releases la versión GUI, restclient-ui-fat-3.7.1.jar
Las URL de nuestro servicio es http://localhost:8080/demo-rest-1.0-SNAPSHOT/rest/persona/ el cual se construye a partir de http://localhost:8080/{nombre_aplicacion}/rest/persona/

Observar que he seleccionado String body como tipo de contenido y application/json como formato y UTF-8 como codificación.

Puedes descargar el código fuente desde mi repositorio en GitHub 

El protocolo HTTP

¿Por qué debo conocer el protocolo el HTTP?

En Java es muy común usar la tecnología Servlets y RESTful para crear aplicaciones Cliente-Servidor, estas tecnologías usan el protocolo HTTP, para nosotros es transparente y podríamos pasar por alto este protocolo. Sin embargo, tener conocimientos del protocolo HTTP no está de más, y si eres curioso como yo, estarás deseoso de saber como funciona este protocolo.

El protocolo HTTP (Hypertext Transfer Protocol) es un estandard que define como un cliente web se comunica con un servidor y como la información es transferida desde el servidor hacía el cliente. Aunque HTTP es usualmente usado para transferir documentos HTML e imágenes embebidos en el documento HTML, HTTP es agnóstico al formato de los datos. HTTP puede ser usado para transferir imágenes, documentos Word, programas .exe, o cualquier cosa que pueda ser representado en bytes. Para escribir programas que usen HTTP, tu necesitas entender HTPP a un nivel de profundidad mucho mayor que el de un diseñador de paginas web. Escribiré una serie de entradas con el fin de mostrarte lo que pasa detrás del telón cuando tu ingresas un dirección web en la barra de tu navegador web.

HTTP es el protocolo estandard para la comunicación entre navegadores web y servidores web. HTTP especifica como un cliente y un servidor establecen una conexión, como el cliente solicita datos al servidor, como el servidor responde a esta petición, y finalmente, como la conexión es cerrada.