Tutorial REST

Tutorial Servicios Web
1. Servicios Web con REST
Como ya hemos usado SOAP para WebService, podemos afirmar que es
bien fácil de diseñar, pero algo complicado de consumir: se necesita toda
una API para construir los clientes utilizando el WSDL.
Además, con SOAP se permite crear un solo servicio y ponerle varios
métodos. Esto puede llevar a un mal diseño del servicio ya que podría tener
un servicio que haga de todo: por ejemplo, un servicio de manejo de
Clientes que permita también manejar Proveedores.
RESTful es una propuesta muy interesante que permite manejar los
servicios web con métodos definidos, manteniendo la simpleza del protocolo
como XML, pero que cada servicio sea identificado únicamente con un solo
URI.
En este tutorial veremos cómo crear un Servicio RESTful usando NetBeans.
Cabe destacar que los servicios de las redes sociales como Flickr, Twitter,
Facebook, etc son basados en RESTful.
Para este ejemplo usaremos NetBeans 7.2, y GlassFish v3.1.2, pero igual
con oras versiones también funciona.
Para comenzar, debemos entender que necesitamos de una clase para
manejar un servicio. En esta clase solo pueden haber máximo cuatro
métodos públicos que son ejecutados por los cuatro métodos HTTP
disponibles para RESTful:
1.
2.
3.
4.
GET
POST
DELETE
PUT
Los métodos GET y POST son conocidos en los formularios (<form
method="post" />). Cada uno de estos métodos determina la acción que
hará el REST sobre nuestra aplicación. No deben haber más de un GET o
POST o DELETE o PUT, solo tiene que haber uno de cada método. 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
aplicación
3. DELETE: Para eliminar un objeto (instancia de identidad)
4. PUT: Para actualizar un objeto.
Esto es como un CRUD, pues eso es lo que es: los métodos para hacer
mantenimiento a una entidad de la aplicación. Entonces, la clase que deberá
tener estos métodos es como una clases EJB Facade de una aplicación
Java EE. Por tanto, esta clase se llamará "Recurso", funcionará como un
EJB, solo manejará la persistencia de una entidad, pero será accedido
desde la web.
2. Creando el proyecto y configurando REST
Crear un proyecto web normal en NetBeans. Darle el nombre
SimpleRESTweb. Este proyecto hará un simple cálculo de factorial.
Luego, crearemos una clase común y silvestre, llamada FactorialResource.
Tendrá (por ahora) un método llamado factorial()
public class FactorialResource {
public long factorial (long base){
if (base >= 1){
return factorial (base -1) * base;
}
return 1;
}
}
3. Creación del EJB
Agreguemos la notación @Stateless al inicio de la clase. Esto convierte
automáticamente a nuestra clase en un EJB.
Luego, seguido al @Stateless agregamos la anotación @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 característica en la aplicación... por tanto pedirá dónde estará activado
todos los recursos REST.
Seleccionar la primera opción, utilizaremos el dado por defecto
(/webresources). Clic en Ok.
Y con esto, nuestra clase ya es un recurso REST.
Pero aún este recurso no tiene métodos. Ahora veremos cómo convertir
nuestro método convencional en un método REST.
4. Creando un método REST
Recordemos que solo podemos crear un método de tipo GET,POST,PUT y
DELETE. Y como el método factorial nos deberá devolver un solo valor
según el parámetro que le especificamos, usaremos el tipo GET.
Para ello agregamos la anotación @GET antes del método.
Y con esto, nuestro recurso ya tiene un método.
Antes de continuar, los valores que se reciben desde el recurso REST
deben ser objetos. Por tanto, nuestro método debe cambiar un poco para
que no devuelva un long, sino un java.lang.String.
Además, debemos indicar que el parámetro base del método Java factorial
será recibido via URL con el nombrebase. Es decir, se llamará al URL así
..../factorial?base=5
Para ello usaremos la notación @QueryParam antes de la declaración del
parámetro y ponemos el nombre de la cadena query.
import javax.ejb.Stateless;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.QueryParam;
@Stateless
@Path ("/factorial")
public class FactorialResource {
/**
*
* @param base
* @return
*/
@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 parámetro de la cadena query podría ser diferente al del
método java.
//....
@GET
public String factorial(@QueryParam("numero") long base) {
//....
Pero si se hace eso, se debería 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
diseñador de la aplicación.
5. Probando la Aplicación
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.
El proyecto se puede probar tres maneras. La primera es la más fácil,
usando la URL. Bastará con abrir nuestro navegador y escribir el URL del
proyecto:
http://localhost:8080/SimpleRESTweb/webresources/factorial?base=10
Este URL está compuesto de lo siguiente:
•
•
•
•
SimpleRESTweb: El contexto de la aplicación. Que generalmente es el
nombre del proyecto.
webresources: Ubicación de los recursos REST de la aplicación. Este
nombre nos lo pidió el NetBeans cuando guardamos la clase Java por
primera vez con la notación @Path ya que detectó que tenía recursos
REST.
factorial: Es el nombre de nuestro recurso (Definido por la anotación
@Path)
base: Es el parámetro del recurso. Justamente es una cadena Query.
El resultado debe mostrarse tan simple como una web sin formato ni nada
La segunda manera que muestro cómo probar este recurso REST es
usando un formulario HTML. Escribamos lo siguiente en el index.jsp
<body>
<h1>Calculando factorial</h1>
<form action="webresources/factorial">
Base: <input name="base" type="text" />
<button>Calcular</button>
</form>
</body>
Y la tercera forma (que es la más profesional) es usando el NetBeans.
Hacemos clic derecho sobre el ícono del proyecto y seleccionamos "Test
RESTful WebService".
Con esto, el IDE creará una página local que accederá al WADL de la
aplicación y se mostrará en el navegador web.
El WADL es análogo 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 parámetros (solo base) que están
disponibles para este recurso. Probamos escribiendo valores en el parámetro,
y hacemos clic en "Test".
5. Probando la Aplicación
Todo servicio web no es útil si no se sabe cómo consumir. Aqui mostraremos
cómo consumir este simple REST.
Usando JavaScript
Para consumir desde JavaScript, se debería utilizar la técnica AJAX. Y en vez
de hacer toda la biblioteca de consumir AJAX con JavaScript, usaremos algo
ya hecho como el jQuery.
Crearemos una página 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=UTF-8">
</head>
<body>
<h2>Calcular factorial</h2>
Número:<input type="text" name="base" id="base"/>
<button type="button" id="calcularBtn">Calcular</button>
<div id="resultado">
Resultado:
</div>
<script type="text/javascript">
jQuery("#calcularBtn").click(function(){
var base = jQuery("#base").val();
jQuery.get("http://localhost:8080/SimpleRESTweb/webresources/factorial",{bas
e:base},
function(resultado){jQuery("#resultado").text(resultado) })
})
</script>
</body>
</html>
Esta HTML funciona desde Firefox cuando se ejecuta desde el NetBeans,
Usando Java
Con NetBeans más el complemento Jersey, se nos hace muy fácil consumir
servicios REST. Para integrarlo con el IDE, necesitamos registrar el WADL.
Esta URL lo podemos obtener así: http://host:puerto/contextoweb/rwebesources/application.wadl
Para nuestro ejemplo, este es
http://localhost:8080/SimpleRESTweb/webresources/application.wadl
Podemos abrirlo desde el navegador y se nos mostrará un XML que contiene la
definición de los recursos (/factorial) y los parámetros de cada método. En este
caso hay un método GET y tiene como parámetro 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 y hacemos clic derecho
sobre el nodo "Web Services" y seleccionamos "Add Web Service..."
Luego, en la entrada de URL, pegamos la dirección 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 y seleccionamos la categoría "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 opción "Select the REST resource" seleccionemos
la opción "From Project" y en Package “cliente”
... y hagamos clic en "Browse" para seleccionar el WebService que acabamos
de hacer.
Nota: Si no se puede registrar el servicio pruébelo con la opción de un recurso
en otro proyecto.
y clic en "Finish". Listo, el IDE nos creará la clase FactorialClient que contendrá
los recursos necesarios para acceder al servicio REST.
Ahora, ¿cómo se consume esto?... en nuestra clase Java solo debemos
instanciar la clase, pasarle el parámetro y recibir el valor.
public static void main (String[] args){
FactorialClient client = new FactorialClient();
long base = 10;
String resultado = client.factorial(String.valueOf(base));
System.out.println("Resultado: " + resultado);
}