¿Qué es REST y para qué sirve una API REST?

Actualmente la gran mayoría de proyectos de desarrollo de software apuntan a disponibilizar un producto o dar acceso a un servicio a través de la red. Por esto, es muy importante conocer la gran cantidad de estándares, paradigmas y protocolos que entran en juego. Para ser concreto, es muy común ver en los requisitos de ofertas laborales de desarrollo web, que se pida conocer y dominar el desarrollo bajo lineamientos RESTful o con simplemente REST. Por todo esto, me pareció interesante hablar sobre esto.

¿Qué es REST?

Intentando definirlo de forma sencilla, podríamos decir que REST es una arquitecta compuesta por una serie de reglas estandarizadas. Estás reglas, ayudan al programador a saber como implementar la capa encargada de la comunicación, o también conocida como la capa de http o de presentación, de forma que sea "compatible" con otras aplicaciones. Es decir, REST se limita a definir un acuerdo para representar la información entrante y saliente (solicitud y respuesta), así como la forma invocación (endpoint). Y lo que suceda en las capas inferiores, como por ejemplo servicios de negocios y capas de acceso a datos, no son su responsabilidad.

En esta imagen se ve una representación de un proyecto definido en tres capas con sus responsabilidades. Como se puede ver marcado en verde, REST tiene injerencia sobre la capa encargada de la comunicación, en este caso un controller.

Características

Para entender en detalle lo dicho anteriormente, hay que profundizar en los lineamientos y los componentes que estos impactan.

Stateless

Si se busca la definición tipo diccionario, se encuentra que REST significa transferencia de representación de estado (Representational State Transfer). Transferencia se puede asociar a la comunicación, estado a la información que se transmite y representación a la forma en que se organizan los datos. Sin embargo, el nombre suele generar confusiones, ya que REST se caracteriza por ser "Stateless", es decir que no se persiste el estado. Para acceder cierta información se tiene que realizar una solicitud y para la cual se devolverá la información asociada (respuesta), pero una vez finalizado este flujo depende del solicitante que esa información se almacene. Si se quiere volver a obtener la información habría que realizar una nueva solicitud.

Definición de endpoints y URIs

Otra de las características destacables de REST, es que organiza cada consulta (request) orientado al recurso. Por esto se puede apreciar que las URIs de cada caso suele contener el nombre del recurso, los atributos y parámetros para realizar filtros. Cabe aclarar que URI es la conjunción de la URL (generalmente es el dominio) y la URN que es la cadena de caracteres que representa el path o recurso al que se apunta. En resumen, estos son ejemplos de como se arman las URIs de los endpoints bajo REST:

Verbos HTTP

Para poder realizar las solicitudes y realizar operaciones con los recursos, además de la URI se utilizan verbos que describen la acción a realizar. Estas acciones son descritas por los clásicos verbos Http: GET, POST, PUT, PATCH y DELETE entre los más conocidos. El verbo GET se usa para solicitar recursos o información, mientras que POST se usa para insertar información nueva, por su parte PUT y PATCH se usan para actualizar información existente. En estos últimos hay una salvedad, es que mientras que el PATCH permite actualizar partes de un recurso, o algunos atributos de un objeto/entidad, por su parte el PUT actualiza "pisando" toda la estructura del recurso. Por último, se encuentra el DELETE que se utiliza para solicitar la eliminación un recurso o información.

Tipado de la información

Por todo lo mencionado anteriormente, podemos resumir que para una solicitud REST requerimos definir un URI y especificar la acción a realizar mediante el verbo HTTP. En solicitudes tipo GET o DELETE, la información como parámetros y filtros de consulta viajan en la misma URI. En el caso de acciones como POST, PUT y PATCH esto queda corto. Como se está enviando un recurso de tamaño variable, según su definición, esta información se suele mandar en el cuerpo (body) de la solicitud en formato de JSON. De esta forma, se asegura que todas las request adecúen la estructura de la información de forma que sea entendible.

Aquí podemos ver una request o solicitud del tipo POST, en la que se van a insertar una lista de países. La información está definida en JSON, donde cada país es un objeto contenido en una lista.

Entonces ¿Qué sería un API REST?

Para explicar este concepto primero hay que entender que una API. Sí se busca la definición en su buscador de confianza, se encontrará que significa "interfaz de programación de aplicaciones". En castellano, esto quiere decir que una API es una capa o "interfaz" entre un recurso y el consumidor del mismo. Esta interfaz permite facilitar el acceso y operatoria de ese recurso, por ejemplo, operaciones contra una base de datos. Es decir, es un programa o software intermediario.

Un claro ejemplo es el del restaurant, donde se encuentra el cliente y la cocina. El cliente no va a ir a la cocina a pedir el plato 15 si quiere pastas, ya que desconoce la terminología interna. En la realidad, suele haber un mozo que va a ser el intermediario para tomar la orden del cliente. Como es su responsabilidad conocer las definiciones internas, va saber que a la cocina le tiene que pedir que preparen el plato 15, para que cuando la preparación esté finalizada se lo entregará al cliente. En este ejemplo el mozo sería una API entre el cliente y la cocina.

Ahora para entender que es una API REST basta con unir los conceptos. Una API por si sola es simplemente un software que actúa de nexo. Si se le aplican los lineamientos REST, estaría orientada a facilitar una comunicación por una red como internet. En decir, se podría definir una API REST como una aplicación que actúa como interfaz entre un cliente y un servidor (web, multimedia, base de datos, etc), brindando acceso a los recursos por medio de los endpoints expuestos.

Un detalle a tener en cuenta es que las API REST suelen dar acceso al recurso a múltiples clientes, los cuales no suelen ser del mismo tipo. Estos clientes pueden ser una web, una aplicación móvil u otro servidor. Lo importante aquí, sin importar las tecnologías propias que implementen, todos son capaces de acceder a los recursos, ya que realizan solicitudes equivalentes al regirse por los lineamientos.

¿Existen otros protocolos?

Si bien REST hoy está de moda y es posiblemente el más demandado, no es el único protocolo aplicable a desarrollo web. Entre los más conocidos también se encuentran SOAP, que a diferencia de REST es utilizado principalmente para WS (webServices) y se caracteriza por ser mucho más complejo. Por esto SOAP perdió popularidad, ya que REST en comparación es mucho más simple, fácil de aprender e implementar. Otra característica a destacar, es que en SOAP se suele "hablar" en xml tanto para la solicitud cono para la respuesta. Y una diferencia muy importante es que mientras en REST se intenta representar en torno a un recurso, en SOAP se representan servicios. Así que si en REST vemos una URI con el nombre del recurso y sus filtros, en SOAP se podrá ver una URL de ubicación y una estructura de solicitud XML, que cuente entre sus atributos la invocación a un servicio, por ejemplo: <input function="listarClientes"></input>.

Recursos y recomendaciones

Para cerrar este post quiero dejar recursos que sirven para aplicar lo visto, ya que en el proceso de desarrollo es muy común ejecutar solicitudes de prueba para validar la implementación realizada. Para facilitar estas tareas la mejor recomendación que puedo hacer es Postman, ya que es el más conocido y el que uso. Aunque si se quiere una alternativa también recomiendo Insomnia.

Para armar las estructuras en JSON, validar el correcto armado o simplemente formatear, recomiendo usar Json lint. También recomendar JsonCrack para facilitar la visualización de los JSON muy complejos y cargados de información.

Por último, recomendar no quedarse solo con lo mencionado en este artículo, ya que los conceptos son más profundos. Lo aquí mencionado es una explicación y acercamiento a estos temas, por lo que lo mejor es ponerlo en practica y seguir investigando si se conocer en detalle.

Solamente queda agradecerte si llegaste hasta acá y animarte a contactarme si tienes alguna duda, sugerencia, corrección o aporte para el artículo. Ya que todavía no me digné a implementar el sistema de comentarios, te invito a escribirme por correo electrónico o hablarme directamente desde Telegram. Sin más que agregar, les dejo saludos y nos leemos en otra publicación.