Header Ads Widget

Ticker

6/recent/ticker-posts

Hydra para las API de Hypermedia: ventajas, componentes y ejemplos

 ¿Qué pasaría si los clientes de API pudieran explorar y comprender los recursos en tiempo de ejecución? En lugar de estar codificados contra versiones específicas de API específicas, podrían identificar datos y funcionalidades accesibles a medida que avanzan a través de una API, tomando medidas adicionales basadas en la entrada del usuario, algoritmos simples o incluso inteligencia artificial.

Esto es exactamente lo que pretenden lograr las API de hipermedia, e Hydra es uno de los pocos marcos estandarizados que describe cómo deben construirse estas API y sus clientes correspondientes. En este artículo, veremos los beneficios de usar un marco como Hydra, sus componentes y algunos ejemplos prácticos de cómo funciona.

Este artículo sirve como una descripción general de alto nivel de Hydra. Consulte el Vocabulario básico de Hydra para obtener una lista de características y convenciones específicas. Para obtener una descripción más detallada de Hydra, vea Bringing Hypermedia to the Masses , una charla de Tomasz Pluskiewicz impartida en la Cumbre de la Plataforma de 2019.

¿Qué es Hydra?

Hydra es un vocabulario que busca simplificar el desarrollo y consumo de API web impulsadas por hipermedia. Es una respuesta a la infame restricción del diseño de API RESTful, Hypermedia como el motor del estado de la aplicación , que distingue las API REST verdaderas de sus contrapartes similares a REST .

La cuarta y última restricción de la interfaz uniforme [en el diseño de API RESTful] es que el estado de la aplicación debe expresarse dinámicamente a través de hipermedia (conocido en forma abreviada como HATEOAS). Esto significa que, además de devolver una representación del recurso en cuestión, una solicitud también debe cumplirse con instrucciones sobre cómo interactuar más con el recurso o la API en su conjunto.

En particular, al acceder a un recurso, el cliente debe recibir información sobre las acciones que se pueden realizar en ese recurso. Estas acciones deben ir acompañadas de referencias de hipervínculos a URI relevantes.

¿Qué problema resuelve Hydra?

Las promesas de las API web hipermedia son muchas: explorabilidad dinámica, documentación en línea y no más URI de recursos codificados, entre otros. Sin embargo, en la práctica, las API de hipermedia se han adoptado lentamente. Una razón de esto es que no existe un marco estandarizado para reconocer o consumir controles hipermedia . Como resultado, los clientes aún deben estar codificados contra las implementaciones de hipermedia utilizadas en API específicas, lo que plantea la pregunta, ¿por qué molestarse en absoluto?

Hydra tiene como objetivo abordar este problema proporcionando un vocabulario común para los conceptos que se ven con frecuencia en las API web.

Bloques de construcción de Hydra

En realidad, Hydra consta de dos partes clave. Existe el vocabulario muy importante mencionado anteriormente, conocido como Hydra Core Vocabulary , pero también hay un formato para hacer referencia a datos vinculados (generalmente JSON-LD ), también conocido como formato de serialización RDF.

JSON-LD

JSON-LD es un estándar W3C que define cómo hacer referencia a datos vinculados en JSON, lo que lo convierte en un ejemplo de un formato de serialización RDF (o Resource Description Framework ). Es totalmente compatible con JSON, lo que quiere decir que agrega funcionalidad sin afectar el comportamiento existente de las aplicaciones o herramientas basadas en JSON.

Una de las ideas principales en cualquier formato de serialización RDF, incluido JSON-LD, es que los valores se asignan a formatos estandarizados (según un vocabulario común como schema.org ) en lugar de claves arbitrarias. Por lo tanto, siempre que el consumidor esté familiarizado con el vocabulario que se utiliza, puede determinar de forma independiente el significado de un par clave-valor sin necesidad de documentación externa.

Vocabulario de Hydra Core

La pièce de résistance de Hydra es, por supuesto, el propio vocabulario de Hydra Core . Si bien JSON-LD hace posible proporcionar prestaciones de hipermedia (léase: enlaces a otros recursos) de forma estandarizada, el vocabulario Hydra Core se puede utilizar para describirlas. El Operationrecurso identifica las operaciones que se pueden realizar en una oferta, mientras que la methodpropiedad define qué método HTTP debe usarse para esa operación.

Hydra Core Vocabulary también proporciona una funcionalidad de "documentación" legible por máquina. Por ejemplo, especifica el entrypointpara la API, así como las clases admitidas y los posibles estados.

Ejemplo

Para ver un ejemplo detallado de Hydra en acción, no busque más allá de la presentación de Tomasz Pluskiewicz Trayendo Hypermedia a las masas en la Cumbre de la Plataforma 2019. Demuestra una aplicación de una sola página que procesa dinámicamente una colección de recursos, así como los propios recursos, basados ​​en propiedades JSON-LD e Hydra.

Su aplicación prototipo, Wikibus.org , enumera varios artefactos (como folletos) relacionados con el transporte público. En la página de la colección de folletos, la aplicación hace que los elementos de folletos individuales en función de schema:titleschema:imagepropiedades especificadas por JSON-LD.

De manera similar, la aplicación procesa páginas de elementos individuales de forma autónoma, basándose en las schema:imagey otras propiedades especificadas para el objeto. Por ejemplo:

{
  "@context": "https://wikibus-sources.herokuapp.com/_contexts/Brochure",
  "title": "Ernst Auwaerter Clubbus Mediano",
  "wishlistItem": null,
  "@type": [
    "https://wikibus.org/ontology#Source",
    "https://wikibus.org/ontology#Brochure"
  ],
  "@id": "https://sources.wikibus.org/brochure/1182",
  "languages": [
    "langIso:de"
  ],
  "pages": 2,
  "images": {
...
  },
  "content": {
    "@id": "https://sources.wikibus.org/brochure/1182/file",
    "name": "Download PDF",
    "encodingFormat": "application/pdf",
    "contentSize": "7.51 MB",
    "contentUrl": "https://wikibus.blob.core.windows.net/sources1182/EA Clubbus Mediano.pdf",
    "@type": "http://schema.org/MediaObject"
  },
  "contributor": {
    "@id": "https://users.wikibus.org/user/google-oauth2|117957693005245427833"
  }
}

... se convierte en:

Si aún no está convencido de que Hydra está agregando valor aquí, considere esto: podría cambiar los folletos de transporte público con cualquier otro recurso para una experiencia igualmente rica. Dado que las páginas de la aplicación se procesan en tiempo de ejecución, según las propiedades adjuntas al recurso, se necesitaría poco código adicional.

¡Sin mencionar que la aplicación de Tomasz es más que solo lectura! Mirando más de cerca el código , se puede ver que la Hidra se utiliza para anotar varias operaciones con acciones schema.org, como CreateActionUpdateActionDeleteAction, y TransferAction, proporcionando una referencia legible por máquina para clientes inteligentes.

Pensamientos finales

Todavía queda mucho trabajo por hacer antes de que podamos esperar que las API de hipermedia logren una adopción generalizada. Los marcos como Hydra estandarizan el consumo de datos vinculados y prestaciones de hipermedia, lo que constituye un primer paso crucial en el desarrollo de API en las que los recursos y las operaciones se descubren en tiempo de ejecución.

Publicar un comentario

0 Comentarios