RESTful la forma ms ligera de hacer WebServices

Quienes hayan usado SOAP para WebService, sabrn que es bien fcil de disear, pero algo
complicado de consumir: se necesita toda una API para construir los clientes utilizando el
WSDL. Por ejemplo, para PHP se necesita de la biblioteca NuSOAP. Entonces, para lograr
el concepto de "lenguaje nico XML" es un dolor de cabeza. Y ms an si el cliente es tan
simple como JavaScript, manejar XML de SOAP provocara suicidos masivos... o no usar
WebServices.
Adems, con SOAP se permite crear un solo servicio y ponerle varios mtodos. Esto puede
llevar a un mal diseo del servicio ya que podra tener un servicio que haga de todo: por
ejemplo, un servicio de manejo de Clientes que permita tambin manejar Proveedores.
RESTful es una propuesta muy interesante de Roy Fielding que permite manejar los
servicios web con mtodos definidos, manteniendo la simpleza del protocolo como XML,
pero que cada servicio sea identificado nicamente con un solo URI.
En este post veremos cmo crear un Servicio RESTful usando NetBeans, y haremos crecer
de poco a poco nuestro ejemplo... desde hacer operaciones sencillas, hasta manejar
estructuras complejas.
Cabe destacar que los servicios de las redes sociales como Flickr, Twitter, Facebook, etc
son basados en RESTful.
Para este ejemplo usaremos NetBeans 6.9.1, y GlassFish v3.0.1, ya que usaremos las
caractersticas de Java EE6. Con GlassFish v.2 igual funciona, y NetBeans ayuda en ello,
Para comenzar, debemos entender que necesitamos de una clase para manejar un servicio.
En esta clase solo pueden haber mximo cuatro mtodos pblicos que son ejecutados por
los cuatro mtodos HTTP disponibles para RESTful:
1. GET
2. POST
3. DELETE
4. PUT

Los mtodos GET y POST son conocidos en los formularios (<form method="post" />)
Tienen algo que ver? S, y lo veremos poco a poco. Cada uno de estos mtodos determina
la accin que har el REST sobre nuestra aplicacin. No deben haber ms de un GET o
POST o DELETE o PUT, solo tiene que haber uno de cada mtodo. Cada uno tiene una
tarea especifica:
1. GET: Para obtener un valor. Puede ser un listado de objetos
2. POST: Para guardar un nuevo objeto (instancia de identidada) en la aplicacin
3. DELETE: Para eliminar un objeto (instancia de identidad)
4. PUT: Para actualizar un objeto.
Suena a un mantenimiento CRUD? S, exacto. Eso es lo que es: los mtodos para hacer
mantenimiento a una entidad de la aplicacin. Entonces, la clase que deber tener estos
mtodos es como una clases EJB Facade de una aplicacin Java EE. Por tanto, esta clase se
llamar "Recurso", funcionar como un EJB, solo manejar la persistencia de una etndiad,
pero ser accedido desde la web. Cmo se hace? Bueno, iremos de poco a poco
conociendo cmo hacer un mantenimiento complejo usando nicamente RESTful.

Creando proyecto y configurando REST

Crearemos un proyecto web comn y silvestre en NetBeans. Yo crear uno llamado
SimpleRESTweb. Este proyecto har un simple clculo de factorial. (Aunque a muchos no
les guste, comenzar siempre con una calculadora ya que es el clsico ejemplo de Entrada>Procesamiento->Salida.. lo dems, usando entidades, bases de datos, etc.. es lo mismo,
solo que utiliza ms variables)
Luego, crearemos una clase comn y silvestre, llamada FactorialResource. Tendr (por
ahora) un mtodo llamado factorial()
public class FactorialResource {
public long factorial(long base) {
if (base >= 1) {
return factorial(base - 1) * base;
}
return 1;
}
}

A esta clase se puede crear su TestCase para asegurarnos que funciona correctamente.
Notemos que hasta ahora no hemos hecho nada REST. La diversin comienza aqu:

Agreguemos la notacin @Stateless al inicio de la clase. Esto convierte automticamente

a nuestra clase en un EJB

Luego, seguido al @Stateless agregamos la anotacin @Path("/factorial") Esto indica

que este recurso ser accedido desde la ruta "/factorial" via web. Ahora, guardemos el
archivo... y en ese mismo momento, el NetBeans detectar de que se ha creado un recurso
REST, entonces pedir activar esta caracterstica en la aplicacin... por tanto pedir dnde
estar activado todos los recursos REST.

Utilizaremos el dado por defecto (/resources). Clic en Ok.

Nota de actualizacin: Para NetBeans 7.3, la opcin de crear el recurso REST cambia.
Mirar aqu RESTful con NetBeans 7.3

Nota: En GlassFish v2 (Java EE 5) solo existirn dos opciones

Y con esto, nuestra clase ya es un recurso REST.

Pero an este recurso no tiene mtodos. Ahora veremos cmo convertir nuestro mtodo
convencional en un mtodo REST.

Creando un mtodo REST

Recordemos que solo podemos crear un mtodo de tipo GET,POST,PUT y DELETE. Y
como el mtodo factorial nos deber devolver un solo valor segn el parmetro que le
especificamos, usaremos el tipo GET.
Para ello agregamos la anotacin @GET antes del mtodo.
Y con esto, nuestro recurso ya tiene un mtodo.

Antes de continuar, los valores que se reciben desde el recurso REST deben ser objetos. Por
tanto, nuestro mtodo debe cambiar un poco para que no devuelva un long, sino un
java.lang.String.
Adems, debemos indicar que el parmetro base del mtodo Java factorial ser recibido
via URL con el nombre base. Es decir, se llamar al URL as
..../factorial?base=5

Para ello usaremos la notacin @QueryParam antes de la declaracin del parmetro y

ponemos el nombre de la cadena query.
@Stateless
@Path("/factorial")
public class FactorialResource {
@GET
public String factorial(@QueryParam("base") long base) {
}

return Long.toString($factorial(base));

long $factorial(long base) {

if (base >= 1) {
return $factorial(base - 1) * base;
}
return 1;
}

El nombre del parmetro de la cadena query podra ser diferente al del mtodo java.
//....
@GET
public String factorial(@QueryParam("numero") long base) {
//....

Pero si se hace eso, se debera recordar que para accederlo via URL debe ser con ese mismo
nombre
..../factorial?numero=5

Pero para evitar problemas, usaremos el mismo nombre. Y en caso de ser necesario,
podemos cambiar el nombre. Eso ya queda a criterio del diseador de la aplicacin.

Probando la aplicacin
Pues bien, ahora guardemos el proyecto, hagamos clic derecho sobre el cono de proyecto y
seleccionamos "Deploy". Esperamos a que se compile el proyecto, se ejecute el GlassFish y
se despliegue.
Aqu propondr tres maneras de probar el recurso REST. El primero es el ms fcil, usando
el URL. Bastar con abrir nuestro navegador y escribir el URL del proyecto:
http://localhost:8080/SimpleRESTweb/resources/factorial?base=10

Este URL est compuesto de lo siguiente:

SimpleRESTweb: El contexto de la aplicacin. Que generalmente es el nombre del

proyecto.

resources: Ubicacin de los recursos REST de la aplicacin. Este nombre nos lo

pidi el NetBeans cuando guardamos la clase Java por primera vez con la notacin
@Path ya que detect que tena recursos REST. Si se desea cambiar esta ruta,
hagamos clic derecho en el nodo "RESTful Web Services" del proyecto y
seleccionando "REST Resources Configuration"

factorial: Es el nombre de nuestro recurso (Definido por la anotacin @Path)

base: Es el parmetro del recurso. Justamente es una cadena Query.

El resultado debe mostrarse tan simple como una web sin formato ni nada

Y ese es el resultado. Quizs me digan "hey, pero esto tambin lo puedo hacer con un
servlet". Pues s, pero no es lo mismo, ya que el Servlet puede guardar variables de sesin,
y aqu en REST no... en Servlet se puede formatear en un HTML, pero aqu en REST no,
porque lo que debe devolver es solo dato.
La segunda manera que muestro cmo probar este recurso REST es usando un formulario
HTML. Escribamos lo siguiente en el index.jsp
<body>
<h1>Calculando factorial</h1>
<form action="resources/factorial">
Base: <input name="base" type="text" />
<button>Calcular</button>
</form>
</body>

El resultado saldr en otra pgina.

Y la tercera forma (que es la ms profesional) es usando el NetBeans.
Hacemos clic derecho sobre el cono del proyecto y seleccionamos "Test RESTful
WebService".

Con esto, el IDE crear una pgina local que acceder al WADL de la aplicacin y se
mostrar en el navegador web.

El WADL es anlogo al WSDL de SOAP

Luego, podemos seleccionar del panel izquierdo el recurso que est disponible (en este caso
"factorial")...

... y vemos que nos muestra cuales son los parmetros (solo base) que estn disponibles
para este recurso. Probamos escribiendo valores en el parmetro, y hacemos clic en "Test".

Consumiendo REST
Todo servicio web no es til si no se sabe cmo consumir. En este post mostraremos cmo
consumir este simple REST. En los siguientes post realizaremos recursos que utilizan
objetos complejos.

Usando JavaScript
Para consumir desde JavaScript, se debera utilizar la tcnica AJAX. Y en vez de hacer toda
la biblioteca de consumir AJAX con JavaScript, mejor usamos algo ya hecho... como el

jQuery.
Crearemos una pgina html al que llamaremos test-jquery.html. Y ah pondremos lo
siguiente.
<html>
<head>
<title></title>
<script type="text/javascript"
src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js">
</script>
<meta http-equiv="Content-Type" content="text/html; charset=UTF8">

</head>
<body>
<h2>Calcular factorial</h2>
Nmero:<input type="text" name="base" id="base"/>
<button type="button" id="calcularBtn">Calcular</button>
<div id="resultado">
Resultado: <span></span>
</div>
<script type="text/javascript">
jQuery("#calcularBtn").click(function(){
var base = jQuery("#base").val();

jQuery.get("http://localhost:8080/SimpleRESTweb/resources/factorial",{
base:base
},function(resultado){
jQuery("#resultado span").text(resultado)
})
})
</script>
</body>
</html>

Esta HTML funciona desde Firefox cuando se ejecuta desde el NetBeans,

y funciona en IExplorer si se ejecuta localmente (o sea, abrindolo desde el explorador de

archivos y activar el filtro de ActiveX que advierte el IE).

Usando Java
Con NetBeans ms el complemento Jersey, se nos hace muy fcil consumir servicios REST.
Para integrarlo con el IDE, necesitamos registrar el WADL. Esta URL lo podemos obtener
as: http://host:puerto/contexto-web/resources/application.wadl

Para nuestro ejemplo, este es

http://localhost:8080/SimpleRESTweb/resources/application.wadl
Podemos abrirlo desde el navegador y se nos mostrar un XML que contiene la definicin
de los recursos (/factorial) y los parmetros de cada mtodo. En este caso hay un
mtodo GET y tiene como parmetro un long.

Ahora bien, este URL del WADL lo vamos a necesitar para registrarlo en el NetBeans. En
el IDE vayamos al panel de servicios (Ctrl+5) y hacemos clic derecho sobre el nodo "Web
Services" y seleccionamos "Add Web Service..."

Luego, en la entrada de URL, pegamos la direccin del WADL. Y como nombre de paquete
ponemos simplerest.

Y listo, ya tendremos registrado el WebService en nuestro IDE.

Esto nos permitir utilizar este servicio en cualquiera de nuestras aplicaciones. Por ejemplo,
ahora, en Java.
Hagamos un nuevo proyecto llamado SimpleRESTClientJavaApp.
Ahora, crearemos un nuevo archivo (Ctrl+N) y seleccionamos la categora "Web Services"
y el tipo de archivo "RESTful Java Client"

Luego, en el siguiente paso, pongamos como nombre de la clase FactorialClient, dentro

de la opcin "Select the REST resource" seleccionemos la opcin "IDE Registered"

... y hagamos clic en "Browse" para seleccionar el WebService que acabamos de registrar.

y clic en "Finish". Listo, el IDE nos crear la clase FactorialClient que contendr los
recursos necesarios para acceder al servicio REST.

Ahora, cmo se consume esto?... en nuestra clase Java solo debemos instanciar la clase,
pasarle el parmetro y recibir el valor. Fcil
FactorialClient client = new FactorialClient();
long base = 15;
String resultado = client.factorial(String.class,
String.valueOf(base));
System.out.println("Resultado: " + resultado);