Sin morir en el camino.

Los servicios web nacen de la necesidad de integrar aplicaciones de diferentes tipos sin importar su lenguaje de programación. Esta necesidad no es nueva y REST es una solución que destaca por su simplicida y flexibilidad, lo cual ha llevado a que sea ampliamente usado.

En este artículo vamos a ver en que consiste REST y un ejemplo práctico en el que consumiremos un servicio.

Arquitectura REST

Rest (Representational State Transfer) es un estilo de arquitectura en la que se exponen recursos de una aplicación utilizando HTTP y su filosofía es presentar servicios web autodescriptivos.

Entremos un poco en detalle acerca de HTTP (HyperText Transfer Protocol), este es el estándar que utilizan las páginas web y define como se debe establecer la comunicación entre en un cliente y un servidor. Aunque HTTP define muchos elementos, desde el punto de vista de REST nos interesan principalmente sus métodos y códigos de retorno. A modo de ejemplo y para ponerlos en contexto, cada vez que utilizamos un navegador web y visitamos una página, el navegador envía una solicitud con el método GET y si todo sale bien el servidor nos retornará su contenido y el codigo 200 indicando que todo salió bien.

Ahora que tenemos unas bases fundamentales de HTTP, podemos iniciar realmente con REST.

Recursos

La idea tras REST es presentar los servicios como recursos y para ello utiliza las famosas URLs (Uniform Resource Locator), como por ejemplo la URL de esta página

Servicios Web REST

Donde /servicios-web-rest es el recurso, blog.justaservice.com es la ubicación del recurso y https es el protocolo con el cual acceder, por lo tanto si quisieramos ofrecer un servicio para administrar personas en este blog ofreceriamos un servicio en la siguiente URL

https://blog.justaservice.com/personas

Y para poder interactuar con el servicio de personas, utilizariamos los diferentes métodos de HTTP que actualmente existen y los cuales indagaremos en mas detalle en la siguiente sección.

Métodos HTTP

Los mas usuados en páginas web comunes y corrientes son los métodos GET y POST, donde GET lo utilizamos para pedir información de una página y POST para envíar formularios.

En REST cada uno de estos métodos indica lo que se quiere realizar en el recurso, como bien podria ser consultar, adicionar información o eliminar un recurso especifíco, entremos en detalles por cada uno.

GET

Este método es utilizado para obtener información del recurso, si quisieramos una lista de personas en nuestro servicio web imaginario bastaría con realizar la consulta a la URL del recurso con nuestro método GET, algo asi como

GET https://blog.justaservice.com/personas

Pero existen casos en los que se necesita obtener una persona especifíca, donde las implementaciones comunes suelen tener a cada recurso con un identificador unico, por lo que si quisieramos obtener una persona específica bastaria con agregar el identificador unico al final de la URL, seria algo como

GET https://blog.justaservice.com/personas/1

Donde el numero 1 indicaria el identifcador de la persona específica, pero esto no se limita solo a numeros, podría ser una combinación de letras y números, e incluso carácteres especiales (pero esto es arriesgado por tema de codificación de caráteres).

Finalmente el método GET tiene una particularidad que los otros métodos no tienen y es la posibilidad de utilizar parametros de consulta, los cuales inician con el carácter ? al final de la URL, seguido por el nombre de parametro de consulta un igual (=) y su valor, luego por cada parametro adicional se adiciona amperstand (&) y siguiendo el patron anterior, es decir nombre del parametro de busqueda, signo igual (=) y su correspondiente valor. Todo esto conmunmente con la idea de filtar la información del recurso. Supongamos que deseamos filtar las personas cuyo sexo sea masculino y edad 18 años, la solicitud seria de la siguiente forma

GET https://blog.justaservice.com/personas?sexo=”masculino”&edad=18

POST

Se utiliza para crear un recurso nuevo en el servicio, esto usualmente se realiza utilizando un idetificador único, siguiendo el caso del servicio de personas y si quisieramos crear una nueva persona con el identificador único 2, se debería de realizar la siguiente solicitud

POST https://blog.justaservice.com/personas/2 Contenido

Donde el contenido representa los datos de la persona como nombre, sexo, edad etc. En la sección de contenido veremos en detalle como enviar esta información y las alternativas que tenemos.

Existe otra alternativa en la cual el identificador es asignado automaticamente por el servicio, en estos casos no es necesario enviar el identificador, por el contrario, una vez creado el recurso en el servicio, el servidor nos retornará información del identificador creado y luego podamos consultarlo. En estos casos los común es enviar la solicitud directamente al servicio y se veria de la siguiente forma

POST https://blog.justaservice.com/personas Contenido

No es común pero una implementación final que se puede realizar con el POST es permitir crear multiples recursos a la vez, en la cual se envia una lista de recursos a crear, en el cual la petición ser veria de la siguiente forma

POST https://blog.justaservice.com/personas Lista de Recursos

Este método debe fallar en el caso de que el recurso que se quiera crear este previamente creado, la falla podria ser total o parcial (en caso de multiples recursos)

PATCH

Permite actualizar parcialmente un recurso existente. En el caso de un recurso con identificador único, en donde quisieramos solo actualizar el sexo de una persona (y dejar la demas información intacta) se realizaría una petición de la siguiente forma

PATCH https://blog.justaservice.com/personas/1 Contenido

En este caso el contenido solo tendria el atribuito sexo con el valor correspondiente que se quiera actualizar.

No es muy común, pero una implementación que se podría presentar es la actualización parcial de varios recursos a la vez, para ello se envía una lista con los valores a actualizar y con su correspondiente identificador único, la solicitud se vería de la siguiente forma

PATCH https://blog.justaservice.com/personas Lista de Recursos

Este método debe fallar en el caso de que el recurso a actualizar no este previamente creado y la falla podria ser parcial o total.

PUT

Permite crear o reemplazar completamente un recurso, se puede decir que funciona como el método POST, con la diferencia que no va a fallar si el recurso ya existe, por esto mismo, este método PUT debe manejarse con cuidado.

Si se utiliza un recurso con identificador único, la petición se veria asi

PUT https://blog.justaservice.com/personas/2 Contenido

Donde el contenido se debe tratar como si fuera un recurso completamente nuevo, es decir que si queremos realizar una simple actualización de sexo, tendriamos primero que obtener toda la información del recurso, luego enviarla toda nuevamente pero solo con el cambio de sexo.

Enviar multiples recurso para crear o reemplazar es posible, seria simplemente enviar la lista de recursos con los correspondientes identificadores unicos de cada recurso mas el contenido como si se tratara de un recurso completamente nuevo. La petición se veria de la siguiente forma:

PUT https://blog.justaservice.com/personas Lista de Recursos

Su uso práctico mas que para actualizar es para reemplazar un recurso, sinceramente esto no es muy común, ademas de peligroso, por lo que muchos servicios web no lo implementan.

DELETE

Permite eliminar un recurso, supongamos que queremos eliminar la persona con el identificador unico 2, por lo tanto realizariamos una solicitud de la siguiente forma

DELETE https://blog.justaservice.com/personas/2

Algunos servicios podrian permitir eliminar multiples registros basados en los identificadores, por lo que se podria mandar una lista de recursos solo con el identificador de los servicios a eliminar.

DELETE https://blog.justaservice.com/personas Lista de Recursos

Es poco comun poder eliminar todos los recursos de golpe, pero en caso de estar implementado se realizaria de la siguiente forma

DELETE https://blog.justaservice.com/personas

HEAD

Permite obtener información del recurso, por lo que indicaria que métodos son aceptados y algunos otros temas de interes como seguridad, para obtener información simplemente bastaria con realizar la solicitud de la siguiente manera

HEAD https://blog.justaservice.com/personas

Cabe decir que podría ser igual de importante para recursos con un identificador unico, por lo que si quisiriemos saber información por ejemplo de la persona con identificador 1, realizariamos la siguiente solicitud

HEAD https://blog.justaservice.com/personas/1

Códigos de Retorno

Como parte de HTTP cada vez que se realiza una solicitud, se pueden obtener multiples respuestas, estas van desde resultados satisfactorios y multiples tipos de errores.

A continuación una lista de las respuestas mas comunes, relacionadas con los diferentes métodos HTTP.

Código	Texto	Métodos
200	Ok	GET, PATCH, PUT, DELETE
201	Created	POST
304	Not Modified	PATCH, PUT
400	Bad Request	All
401	Unauthorized	All
404	Not Found	All
500	Internal Server Error	All

Contenido

Lo común de los servicios web es utilizar JSON (JavaScript Object Notation) tanto para realizar peticiones como para obtener los resultados, sin embargo podemos manejar el contenido en cualquier otro formato como lo serian YAML (Yet Another Markup Language), XML (eXtensible Markup Language), e incluso algun lenguaje o formato creado por nosostros mismos, y para ir mas alla, no solo con texto, tambien podriamos realizar realizar la interacción del contenido con binarios, archivos comprimidos, imagenes o cualquier otro tipo de archivo soportado por un computador. Las posibilidades referente al contenido es muy amplio.

Adicionalmente un servicio podría soportar multiples tipos de contenidos a la vez, los cuales se pueden negociar utilizando cabeceras HTTP entre el cliente y el servidor. Las cabeceras que se utilizan son Accept y Content-Type.

El escoger el tipo de contenido puede depender de cada servicio en si mismo, pero siempre se debe tratar de mantener la simplicidad y tener en mente la facilidad de su uso.

JSON suele ser muy utilizado debido a que usualmente los servicios son consumidos por navegadores web (como Chrome, Firefox, etc) y estos navegadores utilizan de forma nativa javascript, con el cual es muy sencillo acceder, modificar e interactuar con contenido JSON.

Describiendo Servicios

Los servicios web REST deben ser auto descriptivos, sin embargo pueden existir algunas razones para los cuales deberiamos tener un indice o una forma de describir nuestro servicio, como podrian ser

• El detalle del contenido aceptado y que se puede esperar
• Los posibles codigos de respuesta que se pueden esperar por cada método y su gestión de errores.
• En caso de que un método no siga 100% la filosofía REST, indicar como se consume y resultados esperados.

Algunos estándares y herramientas que se pueden mencionar actualmente son

• Raml (Restful API Modeling Language)
• API blueprint (apiary)
• OpenAPI spec (sweager)
• AsyncAPI spec

Al utilizar estos estándares, ademas de presentar de forma detallada el servicio, tambien se abre la puerta a otras posibilidades como serian

• Enfocarse primero en el diseño antes de construir.
• Construir con aplicaciones graficas la descripción del servicio.
• Algunas aplicaciones pueden utilizar estas descripciones para generar una previsualización del servicio e incluso mocks (peticiones que imitan a una real para temas de pruebas).
• Crear integraciones con herramientas automatizadas del lado de los clientes basados en los archivos de descripciones (Salesforce tiene esta funcionalidad y lo integra con otras herramientas como objetos externos y flujos).

Seguridad

Los servicios web pueden ser asegurados de multiples formas, pero lo mas comun es utilizar las herramientas inerentes de HTTP, o con flujos de OAUTH.

La forma mas comun de sesguridad es atraves de un token que se envia en cada solicitud, el cual es secreto y vence cada cierto tiempo.

Adicionalmente cuando un servicio se quiere acceder de una pagina web a otra utilizando el navegador web (usuando javascript), se debe tener en cuenta el tema de CORS (Cross Origin Resource Sharing), para resumirlo, es un tema de seguridad en el servicio define que otros dominios (o paginas web) puden acceder a el.

El tema de la seguridad es bastante ammplio y require todo un articulo aparte.

REST, RESTful and RESTLess

REST es el estándar o estilo de arquitectura, RESTful es la implementación que sigue al pie de la letra REST y finalmente RESTLess es una implementación que no sigue al 100% REST. A modo de ejemplo un servico RESTLess podria utilizar el método HTTP POST para realizar una consulta en donde deberia de ser un HTTP GET, y al no seguir las directrices establecidas por REST se consideraría RESTLess.

EjemploPráctico

Clientes Rest

Para nuestra ejemplo primero necesitamos una herramienta que nos permita enviar y recibir peticiones HTTP. Algunas de las más populares son

• Advance rest client
• Postman
• Curl

Y existen muchas más, pero para esta ejemplo se va a utilizar Postman, el cual es un cliente bastante flexible, robusto, multiplataforma e intuitivo. la aplicación puede ser descargada de su sitio oficial

API REST Publicas

Es posible encontrar servicios REST públicos, los cuales pueden ser de pago o gratuitos. Para nuestro ejemplo podemos seleccionar algun servicio del siguiente repositorio https://github.com/public-apis/public-apis en el cual todos son gratuitos, aunque algunos requiren algun tipo de registro.

El objetivo de este ejemplo es simplemente realizar una petición REST a cualquiera de los servicios y para no complicar la cosa, lo vamos a realizar con un servicio que no requiera ningun tipo de seguridad o registro, por lo que se va a utilizar ip-api, el cual permite obtener la respectiva ubicacion de un computador basado en su IP.

Revisando la documentación simplemente basta con realizar una solicitud con el método GET a una de las URL disponibles según el formato que se desee obtener.

Para nuestro ejercicio vamos a realizarlo con JSON, por lo cual nuestra peticion se veria de la siguiente forma

GET http://ip-api.com/json/{ip}

El cual retornará un JSON con información de interes a la dirección IP.

A continuación el ejemplo en postman:

Aunque bien documentado, fácil de entender y sencillo de utilizar, este servicio caería dentro de la categoría de RESTLess debido a que el formato (JSON, CSV, PHP, etc) debería de manejarse utilizando cabaceras HTTP y la referencia al recurso deberia de ser explicito, es decir el servicio se debería de expresar algo como

GET http://ip-api.com/ip/{ip}

Y soportar la cabecera Accept: application/json

Conclusiones

• Todo servicio web REST debe ser auto descriptivo para facilitar su uso.
• Es difícil encontrar a nivel profesional REST API que realmente sean RESTful, la mayoria caerian en la categoria de RESTLess.
• Unas buenas bases de REST nos permitira crear y utilizar API REST mucho mas fácil.

Gracias por leer.