8.

- Dos ejemplos de una API REST y RESTful:

Ejemplo 1 de API REST
Iniciar sesin
La primera solicitud de la API de REST de una sesin debe ser de inicio de
sesin. Se trata de una solicitud POST que enva las credenciales de usuario en
el cuerpo de la solicitud. Puesto que es una solicitud POST, debe incluir
encabezados Content-Type y Content-Length.
POST /api/2.2/auth/signin HTTP/1.1
HOST: my-server
Content-Type:text/xml
Content-Length: 131
<tsRequest>
<credentials name="administrator" password="passw0rd">
<site contentUrl="" />
</credentials>
</tsRequest>

Ejemplo 2 de API REST

Crear un nuevo recurso
Para crear un nuevo recurso, como un nuevo usuario, debe enviar una solicitud
POST. Esta debe incluir lo siguiente:
Un encabezado X-Tableau-Auth con el token de autenticacin que se
devolvi en la llamada para iniciar sesin.
Un encabezado Content-Length que especifique la longitud de los datos
XML en el cuerpo de la solicitud.
Un encabezado Content-Type definido como text/xml.
Un cuerpo de solicitud con un bloque XML que incluya la informacin para
el nuevo recurso. El XML se define mediante un esquema XML. La
informacin del bloque XML depende del tipo de recurso que est creando.
En el siguiente ejemplo se muestra una solicitud que crea un nuevo usuario.
POST /api/2.2/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users HTTP/1.1
HOST: my-server
X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd
Content-Length: 73
Content-Type: text/xml
<tsRequest>
<user name="NewUser" siteRole="Publisher" />
</tsRequest>

Ejemplo 1 RESTful

La estructura del proyecto en eclipse es la siguiente:

Ahora vamos a necesitar unas dependencias del proyecto de Jersey,

estas dependencias contienen las clases necesarias que necesitar
nuestro proyecto.
Existen diversas implementaciones de la especificacin JAX-RS (Restful
Web Services), una de ellas es la de Jersey y que es la ms comn y la
que necesitamos.
Nuestro pom.xml queda as:

Nuestro servicio har lo siguiente, haremos una peticin a un servicio y

nos regresara la misma informacin en diferentes formatos (xml, texto y
json). La respuesta del servicio depender de la url que invoquemos.
La url seria de la siguiente forma:
/mirecurso/text
/mirecurso/json
/mirecurso/xml

Un servicio se hace referencia mediante una URI o un identificador nico

de un recurso en el servidor, para nuestro caso ser de la siguiente
manera:
http://localhost:8090/TestRestful
Y la gran ventaja es que es muy simple de implementar, tanto como
hacer un GET sobre la url que vemos arriba.
Bueno, ahora en nuestro eclipse, vamos a crear una clase que maneje
las peticiones, nuestra clase se llamar:
MessageResources.java, que es un simple POJO y le agregaremos un par
de anotaciones.

Como vemos, nuestra clase esta anotada con @Path, el cual hace match
con la url que deseamos invocar.
Teniendo esa clase escrita, vamos a implementar los mtodos que van a
manejar los diferentes formatos del servicio y que ser la salida del
mismo:

Como ltimo paso, configuraremos el web.xml para indicarle a Jersey

que cualquier peticin que inicie con /* ser parte de la invocacin de
nuestro servicio. Es simple, es como configurar cualquier servlet que
intercepta las peticiones.

Nuestro web.xml quedara de la siguiente forma.

Eso es todo, cuando el contenedor del Tomcat inicie detectar las clases
anotadas con @Path y las considerar como parte de la URI de nuestro
servicio.
Comprubalo haciendo un GET sobre las siguientes URL's.
http://localhost:8090/TestRestful/mirecurso/xml
http://localhost:8090/TestRestful/mirecurso/json
http://localhost:8090/TestRestful/mirecurso/text
Salida de una prueba local.

Ejemplo 2 RESTful

El servicio ser muy simple, recibir una peticin a una direccin

especfica y retornar un mensaje en texto en algn formato (segn la
peticin), ser como un Hola Mundo en RESTful, pero con ms detalles y
adiciones.
El servicio lo desplegaremos en un servidor Apache Tomcat en su versin
8, se usara la librera Jersey en su versin 2.14 la cual implementa JAXRS2.0. Del .zip de Jersey, tomaremos todos los .jar que estn en cada
una de las carpetas (api, ext y lib).
La estructura de carpetas para nuestro proyecto ser la siguiente:

Estructura de carpetas para el servicio web RESTful con Java y Apache

Tomcat

Una vez descargado apache tomcat lo podremos descomprimir en una

carpeta llamada "servidor" en nuestro disco C:/ para acceder a l
fcilmente, dentro de la carpeta servidor encontraremos otra carpeta
llamada webapps, al interior de sta crearemos una nueva carpeta
llamada RESTful (fijarse en las maysculas y minsculas) y dentro de
sta crearemos otra llamada WEB-INF (debe estar en maysculas), esta
carpeta WEB-INF tendr dentro de s un archivo llamado web.xml, una
carpeta llamada lib y otra llamada classes. Dentro de la carpeta lib
pondremos todos los archivos .jar de .zip de jersey. Dentro de la carpeta
classes pondremos la estructura del paquete de nuestro servicio web
que ser com.aap.ws, quiere decir que la carpeta ws contendr el
archivo .java del servicio web que llamaremos WebService.java.

Ahora veamos el contenido de los archivos WebService.java y web.xml

El archivo WebService.java

El archivo WebService.java ser el cdigo de funcionamiento del servicio

web, ser el que indique qu hacer al recibir peticiones por algn tipo de
mensaje HTTP (put, get, delete, post, etc.).
package com.app.ws; //Esta es la estructura de paquete creada
import javax.ws.rs.*; //Importamos la librera para manejar RESTful
@Path("getMessage/{type}") //Especificamos una ruta que se debe usar para
invocar este mtodo y un parmetro (tipo)
public class WebService {
@GET //Indicamos que este mtodo se ejecutar al recibir una peticin por
get
@Produces({"text/plain", "text/html","text/xml", "application/json"})
//Indicamos que el tipo de salida es texto plano, XML, HTML o JSON
public String mostrarMensaje(@PathParam("type") String tipo) {
//Mtodo que recibe como parametro el valor de type en la URL
if(tipo.equalsIgnoreCase("texto"))
{
return "ste es mi primer servicio RESTful con Java";
}
else if (tipo.equalsIgnoreCase("html"))
{
return "<html lang='es'><head><meta charset='UTF8'/><title>WS</title></head><body><h1>ste es mi primer servicio RESTful
con Java</h1></body></html>";
}
else if(tipo.equalsIgnoreCase("xml"))
{
return
"<?xml
version='1.0'
encoding='UTF-8'?
><root><value>ste
es
mi
primer
servicio
RESTful
con
Java</value></root>";
}
else if(tipo.equalsIgnoreCase("json"))
{
return "{\"root\":{\"value\":\"ste es mi primer servicio RESTful con
Java\"}}";
}
else
{
return "Tipo no soportado";
}
}
}

Tenemos entonces en el cdigo anterior un servicio web que funciona en

la ruta getMessage/type donde type puede ser cualquier cosa, pero solo

se aceptar texto, HTML, XML y JSON si es diferente a estos, se retorna

un mensaje en texto plano diciendo "Tipo no soportado". Hay que notar
que nicamente tenemos un mtodo el cual puede ser llamado usando
el mtodo get de HTTP, es decir que lo podremos invocar incluso desde
el navegador web. Este mtodo al ser el nico posee mltiples tipos
MIME de respuestas (para XML, HTML, JSON y texto plano) que se
especificaron en un pequeo arreglo en el marcador @Produces. Cabe
resaltar que el valor del parmetro enviado por URL se obtiene con la
anotacin @PathParam("type"), ntese que debe coincidir con lo que se
puso en @Path.
Muy bien ahora lo que haremos ser compilar nuestro WebService.java.
Debido a que no estamos usando ningn entorno de desarrollo usaremos
el comando javac desde la consola
cd C:/servidor/webapps/RESTful/WEB-INF
#Nos desplazamos a la carpeta WEB-INF de nuestro servicio web
javac -classpath lib/* classes/com/app/ws/*.java
#Compilamos nuestro .java usando todos los .jar de la carpeta lib
Al ejecutar esto desde la consola tendremos junto
WebService.java un archivo llamado WebService.class.

al

archivo

El archivo web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app
xmlns="http://java.sun.com/xml/ns/javaee" version="3.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
<servlet>
<servlet-name>RESTful</servlet-name>
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>jersey.config.server.provider.packages</param-name>
<param-value>com.app.ws</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>RESTful</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

el valor de <param-value> en <init-param> debe coincidir con la ruta

del paquete donde se encuentra el archivo .java y que <url-pattern>
especifica la ruta donde se "ubicar"" inicialmente el servicio web para
ser invocado segn el valor de la etiqueta @Path. Para este caso al
poner /* indicamos que no es necesario aadir nada a la ruta y que
despus del slash (/) puede ir cualquier cosa; esto quiere decir que una
ruta
para
invocar
nuestro
servicio
web
puede
ser
http://localhost:8080/RESTful/getMessage/xml/, si pusiramos que el
valor de <url-pattern> fuera /servicios/* entonces para invocar el
servicio ya deberamos usar la URL:
http://localhost:8080/RESTful/servicios/getMessage/xml/.
Una vez ya tenemos nuestro archivo WebService.java compilado y
hemos creado nuestro archivo web.xml y todos los archivos, libreras,
carpetas y dems se encuentran en la ruta correcta, solo nos queda
arrancar el servidor Tomcat e invocar nuestro servicio web (usando el
navegador por ejemplo).
Para correr el servidor, tambin lo podemos hacer desde consola o
iniciando directamente el archivo startup.bat en windows o startup.sh en
Linux que se encuentran en la carpeta bin de Tomcat, vemoslo desde
consola:
cd C:/servidor/bin #Vamos a la carpeta bin del servidor
startup
Si
todo
ha
ido
bien,
podemos
ingresar
a
la
URL
http://localhost:8080/RESTful/getMessage/xml/
y
obtendremos
un
mensaje que dice "ste es mi primer servicio RESTful con Java", si
miramos el cdigo fuente de esa pgina podremos ver que el servicio
escribi <?xml version='1.0' encoding='UTF-8'?><root><value>ste es
mi primer servicio RESTful con Java</value></root>
Si
ingresamos
a
la
direccin
http://localhost:8080/RESTful/getMessage/json/
obtendremos
como
respuesta lo siguiente: {"root":{"value":"ste es mi primer servicio
RESTful con Java"}} Notemos que la E tildada se ve mal puesto que el
archivo JSON no posee formato a diferencia del XML y el HTML.
Si
ingresamos
por
ejemplo
a
http://localhost:8080/RESTful/getMessage/php/
obtendremos
como
respuesta: "Tipo no soportado" puesto que PHP no hace parte de
nuestros tipos MIME considerados.

9.- Cul es la finalidad del token?

El Token no es ms que una firma cifrada que permite a nuestro API

identificar al usuario. Pero este Token no se almacena en el servidor, si
no en el lado del cliente y el API es el que se encarga de descifrar ese
Token y redirigir el flujo de la aplicacin en un sentido u otro.

10.- Qu herramientas o servicios y protocolos se

necesitan para que una pgina web pueda consumir
datos de un servicio web?
Web Services Protocol Stack: As se le denomina al conjunto de
servicios y protocolos de los servicios Web.
XML (Extensible Markup Language): Es el formato estndar para los
datos que se vayan a intercambiar.
SOAP (Simple Object Access Protocol) o XML-RPC (XML Remote
Procedure Call): Protocolos sobre los que se establece el intercambio.
Otros protocolos: los datos en XML tambin pueden enviarse de una
aplicacin a otra mediante protocolos normales como HTTP, FTP, o SMTP.
WSDL (Web Services Description Language): Es el lenguaje de la
interfaz pblica para los servicios Web. Es una descripcin basada en
XML de los requisitos funcionales necesarios para establecer una
comunicacin con los servicios Web.
UDDI (Universal Description, Discovery and Integration):
Protocolo para publicar la informacin de los servicios Web. Permite
comprobar qu servicios web estn disponibles.
WS-Security (Web Service Security): Protocolo de seguridad
aceptado como estndar por OASIS (Organization for the Advancement
of Structured Information Standards). Garantiza la autenticacin de los
actores y la confidencialidad de los mensajes enviados.
REST (Representational State Transfer): arquitectura que, haciendo
uso del protocolo HTTP, proporciona una API que utiliza cada uno de sus
mtodos (GET, POST, PUT, DELETE, etc) para poder realizar diferentes
operaciones entre la aplicacin que ofrece el servicio web y el cliente.