Header Ads Widget

Ticker

6/recent/ticker-posts

Herramientas para facilitar el cumplimiento de HATEOAS


 HATEOAS es, en esencia, una propuesta de valor y una definición de lo que debería hacer una API. HATEOAS, o Hypermedia como motor del estado de la aplicación, es una restricción específica sobre la arquitectura REST. Para muchos, sin embargo, HATEOAS parece una adición delicada a la gran cantidad de mejores prácticas de diseño de API.

Parte de esto proviene del hecho de que HATEOAS está rodeado por una hipérbole: algunas definiciones parecen implicar que es la solución a todos los problemas de RESTful, y otras parecen sugerir que es un ejercicio inútil en el espíritu de diseño forzado. La verdad es que ambos campos tienen algunos puntos válidos, lo que hace que HATEOAS sea algo difícil de considerar.

Hoy, discutiremos el cumplimiento de HATEOS . Veremos qué es realmente HATEOAS y qué no es. Una vez que hayamos disipado parte de la hipérbole, discutiremos algunos  formatos  (HAL, JSON-LD, Siren, Spring y otros) que pueden ayudar a que la integración de HATEOAS sea más fácil y más eficiente en su API.

Qué es HATEOAS y qué no es

Toda la conversación sobre el cumplimiento de HATEOAS gira en torno a una propuesta: que HATEOAS tiene un valor intrínseco y, como tal, es algo que debe integrarse de la manera más efectiva y completa posible. Esta proposición depende de la idea de que el hipertexto es un esqueleto fundamental sobre el que reside la web moderna y, como tal, debería ser el marco sobre el que se comunican las API web . Cada función en HATEOAS debe tener un enlace relacionado que permita más recursos y acciones vinculados ; como implementación, es hipermedia encarnado.

Parece haber cierta confusión en cuanto a la relación entre hipermedia y REST que debería discutirse; el propio Roy Fielding ha comentado sobre esta confusión:

Me frustra la cantidad de personas que llaman a cualquier interfaz basada en HTTP una API REST. El ejemplo de hoy es la API REST de SocialSite . Eso es RPC. Grita RPC. […] En otras palabras, si el motor del estado de la aplicación (y por lo tanto la API) no está siendo manejado por hipertexto, entonces no puede ser RESTful y no puede ser una API REST. Período. ¿Hay algún manual roto en algún lugar que deba arreglarse?

En última instancia, HATEOAS es un intento de integrar hipermedia en el diseño RESTful. Sin embargo, hay otra consideración que debe mencionarse: HATEOAS también tiene restricciones de verborrea estrictas, adhiriéndose a las pautas HTTP. Como tal, HATEOAS se puede resumir como un método para implementar hipermedia al tiempo que garantiza que se respete la verborrea según las pautas establecidas.

Argumentos en contra de HATEOAS

Parte de lo que dificulta el cumplimiento es el hecho de que existen algunos argumentos válidos contra HATEOAS en ciertas aplicaciones. El principal de estos argumentos es la idea de que HATEOAS es solo una curita para el cumplimiento de la verborrea que no es HTTP . En otras palabras, si el rigor de la verborrea HTTP no avanzó en el espacio de la API, ¿qué quiere decir que HATEOAS hará alguna diferencia?

También hay un fuerte argumento en el concepto de que HATEOAS carece de claridad semántica . Dado que todo se define por relación, algunos argumentarían que no existe un cliente perfecto que funcione como una API sin dejar de ser capaz de analizar rápida, automática y correctamente cada enlace de relación y sus valores posteriores.

Tangencialmente, hay un argumento relacionado de que HATEOAS no tiene claridad de flujo inverso . Debido a que a menudo no hay una conexión clara de "a a b" y, en cambio, una serie de relaciones, invertir el flujo en una llamada puede resultar en una referencia circular en apariencia.

En última instancia, el principal argumento en contra de HATEOAS es que es una camisa de fuerza de restricciones que parece ofrecer poco a cambio.

Lea también: Diseño de una verdadera máquina de estados REST

El valor de los hipermedia

Si bien los argumentos anteriores son técnicamente válidos, pasan por alto un punto importante: cada uno de esos argumentos es cierto para aplicaciones que ya no necesitan un sistema Hypermedia. Para una API estándar que tiene solo unas pocas llamadas no relacionadas, HATEOAS no tiene sentido. Para una API de empresa a empresa que se conecta a sistemas privados, la visibilidad no es una preocupación y, como tal, HATEOAS no tiene sentido.

Para cualquier sistema que hace necesidad de descubrimiento , sin embargo, HATEOAS es un regalo del cielo. Hypermedia permite que una única URL, una vez contextualizada con la documentación y la orientación adecuadas , se utilice como método para navegar por todo el sistema. Permite una utilización verdaderamente compleja , porque no bloquea la comprensión solo detrás de la documentación; en teoría, y con un cliente compatible con HATEOAS especialmente diseñado, la verborrea en uso es estándar, esperada y entendida, formando un tipo de lengua franca para desarrolladores y usuarios por igual.

También se debe considerar cómo sería la no implementación de un sistema hipermedia si la necesidad estuviera presente. En un sistema que requiere capacidad de detección, sin HATEOAS, todo el descubrimiento debería realizarse manualmente, ya sea mediante la utilización de la documentación o mediante prueba y error. Si bien esto podría rectificarse parcialmente haciendo que el código base sea más fácil de entender y utilizar, la carga de la comprensión no debería recaer completamente en el cliente; después de todo, los clientes mal formados y la falta de comprensión del usuario es lo que hace que todo esto sea un problema para empezar. por lo que esperar que solucionen el problema es similar a "patear la lata por el camino".

En otras palabras, HATEOAS no debe verse como una curita, sino como un tipo de protocolo: cuantas más API lo utilicen y el valor que aporta, más estrictamente tendrán los clientes para restringir su comprensión de la verborrea, y más aparecerán claras las relaciones de datos. Claro, ciertos enfoques y valores de diseño de API no permiten HATEOAS, pero cuando es posible, ofrece suficientes aspectos positivos para superar sus aspectos negativos y ofrecer valor al usuario final .

Lea la opinión del proponente de los hipermedia Asbjørn Ulsberg: REST State Machine Revisited

Formatos y herramientas comunes de HyperMedia

HATEOAS se ha desarrollado bastante y, como tal, existe un cuadro cada vez mayor de ofertas para varios formatos de hipermedia. Si bien algunos de estos son específicamente lenguajes, otros son marcos y herramientas que pueden ayudar a expandir una API ya establecida en el espacio hipermedia.

JSON-LD

JSON es un formato muy común para las API en general, pero tiene una debilidad importante que hace que la adopción de hipermedia sea un problema: JSON no tiene un mecanismo de hipervínculo incorporado. Teniendo en cuenta que los hipervínculos forman la columna vertebral de los hipermedia, esto crea algunos problemas importantes en el cumplimiento de HATEOAS.

JSON-LD es una solución que intenta solucionar el problema. Con el respaldo del World Wide Web Consortium, JSON-LD es esencialmente JSON con una sintaxis adicional diseñada específicamente para recursos vinculados, de ahí, " JSON para documentos vinculados ". JSON-LD utiliza palabras clave que agregan contexto a las funciones existentes en la API, introduciendo información adicional al recurso en un intento de agregar relaciones que se puedan comprender y relacionar más completamente.

Una propuesta de gran valor para JSON-LD es el hecho de que no cambia fundamentalmente la base de código y, como tal, se puede implementar sin afectar la API de ninguna manera significativa y significativa. JSON-LD es mejor, entonces, para las API JSON que no pueden sufrir tiempo de inactividad, no pueden admitir una pista de desarrollo separada para la conversión a un formato hipermedia y para desarrolladores que están sopesando el costo de los hipermedios con sus beneficios.

Un ejemplo simple de cómo se ve JSON-LD:

{
"@context": "https://json-ld.org/contexts/person.jsonld",
"@id": "http://dbpedia.org/resource/John_Lennon",
"nombre": "John Lennon",
"nacido": "1940-10-09",
"cónyuge": "http://dbpedia.org/resource/Cynthia_Lennon"
}

HAL

Una representación visual de cómo está estructurada una representación HAL.

Diseñado por Mike Kelly, HAL es otro formato popular, muy querido por su implementación liviana. HAL utiliza los conceptos cargados de hipermedia de Recursos y Vínculos como metodología para modelar las relaciones entre funciones dentro de la API, con Vínculos que conducen a Recursos integrados adicionales. Los recursos integrados ofrecen el vínculo fundamental entre el estado actual del recurso y el contenido relacionado que se encuentra en el vínculo de relación; por ejemplo, en una API de HAL, una llamada al recurso "usuario" puede tener un recurso integrado de "lista de amigos", que detalla todos los URL de los amigos relacionados con esa URL de usuario singular.

Ejemplo de un recurso integrado en HAL :

{
"_Enlaces": {
"self": {
"href": "http://example.com/api/book/hal-cookbook"
}
},
"_incrustado": {
"autor": {
"_Enlaces": {
"self": {
"href": "http://author-example.com"
}
},
"id": "shahadat",
"nombre": "Shahadat Hossain Khan"
}
},
"id": "hal-cookbook",
"nombre": "Libro de cocina de HAL"
}

HAL es un formato popular debido a su sintaxis liviana , pero tiene un inconveniente importante en comparación con JSON-LD: funciona como un modelo de relaciones, lo que significa que su API podría tener que sufrir cambios significativos para aprovechar los beneficios de HATEOAS . Si bien hay muchas herramientas que facilitan esta conversión, es difícil de vender para las API de larga data que no pueden tener tiempo de inactividad y no pueden admitir el desarrollo bifurcado. Dicho esto, la experiencia del usuario es buena y los desarrolladores aprecian la simplicidad de la sintaxis, por lo que para proyectos nuevos (e incluso proyectos existentes con tiempo y esfuerzo de sobra), HAL es una gran opción.

SIRENA

SIREN funciona utilizando los conceptos de Entidades, Propiedades y Vínculos. Una entidad es esencialmente una entidad genérica que representa un recurso. Este recurso puede tener una clase opcional que defina aún más el tipo de recurso, formando un tipo de documentación ad-hoc en línea. Esta definición se da a través de Propiedades; pares clave-valor que definen el recurso con información y contexto adicionales. Desde aquí, SIREN utiliza enlaces , que funcionan exactamente como cabría esperar, definiendo una relación y el enlace en sí.

Si bien SIREN funciona con un conjunto de enfoques bastante estándar, una de las cosas más importantes que agrega a la conversación es una definición de acciones . Muchos estados de Hypermedia en realidad no explican o dictan qué acciones se pueden tomar en un recurso, lo que significa que una vez que se comprende y se descubre la URI, puede que no sea fácil de utilizar. SIREN corrige esto al señalar las Acciones permitidas, anotando el método, los campos sobre los que se puede actuar, la clase de acciones y más. En última instancia, esto hace mucho para que los sistemas HATEOAS sean tanto detectables como utilizables, que es un problema importante señalado por los detractores de HATEOAS.

ION

ION es un tipo de hipermedia más nuevo que busca establecer una serie de nombres y versiones de tipos de medios en su código base, definiendo la relación entre los recursos mediante enlaces y definiciones de objetos. Debido a que ION es relativamente nuevo, es difícil argumentar objetivamente la propuesta de valor a largo plazo de la solución.

Dicho esto, ION hace un muy buen trabajo al proporcionar enlaces serializados a contenido relacionado, y lo hace de una manera muy clara. Sin embargo, tiene los mismos inconvenientes de tener un enfoque y una sintaxis específicos, lo que puede hacer que la utilización sea más difícil para las bases de código ya desarrolladas.

API JSON

JSON API es un fuerte competidor para establecer contenido vinculado debido a su dependencia de la formación de un gráfico de datos. Si bien ha habido muchas implementaciones de los llamados "datos graficados", quizás la más significativa de las cuales sea GraphQL , JSON API utiliza el enfoque de "Documentos compuestos" para incluir recursos adicionales con el recurso solicitado para el solicitante. Luego, los clientes pueden reducir la cantidad de datos que se transmiten utilizando Sparse Fieldsets para limitar los datos solo a lo que realmente se solicita, recibiendo así contenido vinculado y al mismo tiempo asegurando la administración del tamaño de la respuesta.

Cabe señalar también que, además de las implicaciones hipermedia de JSON API, la solución ofrece capacidad de almacenamiento en caché y paginación que otras soluciones de gráficos como GraphQL no ofrecen. De esta manera, JSON API ofrece una amplia gama de beneficios y funciones que deben tenerse en cuenta. Nuevamente, al igual que otras opciones en esta lista, esto requiere un tiempo significativo para la implementación y una sintaxis específica, y para muchos detractores, esto puede ser un inconveniente significativo.

Lea nuestra revisión de la API JSON: Los beneficios de usar la API JSON

Primavera de Pivotal

Hay una variedad de métodos que los desarrolladores pueden utilizar para construir sistemas compatibles con HATEOAS . Si bien estos varían de una aplicación a otra, se pueden separar en una de unas pocas categorías. Una de esas categorías es el concepto de cumplir con HATEOAS mediante la implementación de un marco desde cero. Al abordar el problema en la base misma del desarrollo, muchos de los costos de la etapa tardía de integración y conversión pueden evitarse por completo; en otras palabras, es más barato en términos de tiempo y esfuerzo construir un sistema compatible con HATEOAS desde cero. que revisar después del hecho.

Spring aborda estos problemas en HATEOAS proporcionando un marco a través del cual construir su API. Pivotal utiliza una clase de representación y una propiedad _links para definir el contenido de datos relacionados para recursos específicos. Toda esta interacción es manejada por controladores específicos, que enrutan la entrada del usuario y las interacciones del modelo en función del controlador apropiado y la lógica de la aplicación para el subconjunto de interacciones dado.

Ripozo

Otra herramienta sería Ripozo . Si bien no es necesariamente un marco en el sentido de Spring, Ripozo actúa casi como un contenedor , definiendo enlaces entre recursos utilizando un par de clase / definición . Una clase como "Recurso" tendría valores que incluyen "id", "tipo", "miembro", etc. Estas clases se pueden usar para formar una red de recursos vinculados que da como resultado una API que es verdaderamente autodescriptiva, lo que permite el autodescubrimiento.

Uno de los principales puntos de venta de Ripozo es que tiene una amplia variedad de opciones para marcos, lenguajes e implementaciones. Además de esto, hay integraciones directas de marcos con Flash y Django, así como dos integraciones directas de bases de datos con SQLAlchemy y Cassandra.

Relevante: Definición de servicios web con estado y sin estado

Conclusión

Si bien hay puntos a favor y en contra de HATEOAS, el concepto subyacente de hipermedia es simplemente demasiado valioso para ignorarlo. Si bien HATEOAS puede no ser una solución mágica, en muchos casos orientados a REST, ofrece una propuesta de valor que hace que su adopción sea más beneficiosa que la suma de sus inconvenientes.

Dicho esto, la implementación es, por supuesto, completamente contextual para la situación en cuestión: para las API que no desean adoptar HATEOAS o hipermedia, la falta de adopción puede verse tanto como una característica como un inconveniente. En esas situaciones, especialmente en el caso de que no se implemente hipermedia, estas API no deben considerarse ni llamarse RESTful según las propias definiciones del creador.

Publicar un comentario

0 Comentarios