urls restful nouns net api rest discovery hateoas

nouns - restful api net



Descubrimiento de tiempo de ejecución de API RESTful/diseño de cliente HATEOAS (8)

Creo que el punto importante acerca de HATEOAS no es que sea algo del lado santo del cliente, sino que aísla al cliente de los cambios del URI; se supone que está utilizando relaciones de enlace conocidas (o desarrolladas a medida) que permitirán que el sistema saber qué enlace para un objeto es la forma editable. El punto importante es usar un tipo de emdia que sea compatible con hipermedios (por ejemplo, HTML, XHTML, etc.).

Para una startup SaaS en la que participo, estoy construyendo una API web RESTful y un par de aplicaciones cliente en diferentes plataformas que la consumen. Creo que tengo la API resuelta, pero ahora estoy recurriendo a los clientes. Como he estado leyendo sobre REST, veo que una parte clave de REST es el descubrimiento , pero parece que hay mucho debate entre dos interpretaciones diferentes de lo que realmente significa el descubrimiento:

  1. Descubrimiento del desarrollador : el desarrollador codifica grandes cantidades de detalles de API en el cliente, como URI de recursos, parámetros de consulta, métodos HTTP admitidos y otros detalles que han descubierto al examinar los documentos y experimentar con las respuestas de la API. Este tipo de descubrimiento en mi humilde opinión necesita un enlace genial y la pregunta de control de versiones de la API, y conduce al acoplamiento estricto del código del cliente con la API. No es mucho mejor que si se usa una colección de RPC bien documentada.

  2. Descubrimiento en tiempo de ejecución : la aplicación del cliente puede descubrir todo lo que necesita con poca o ninguna información fuera de banda (presumiblemente, solo un conocimiento de los tipos de medios que maneja la API). Los enlaces pueden estar muy calientes. Pero para hacer que la API sea muy eficiente, parece que se necesitan muchas plantillas de enlace para los parámetros de consulta, lo que hace que la información fuera de banda vuelva a aparecer. Posiblemente haya otras dificultades en las que aún no he pensado ya que no las he tenido. llegado a ese punto en el desarrollo. Pero me gusta la idea de un acoplamiento flexible.

El descubrimiento en tiempo de ejecución parece ser el santo grial de REST, pero veo muy poca discusión acerca de cómo implementar dicho cliente. Casi todas las fuentes de REST que he encontrado parecen suponer el descubrimiento del desarrollador. ¿Alguien sabe de algunos recursos de descubrimiento de Runtime? ¿Mejores prácticas? ¿Ejemplos o bibliotecas con código real? Estoy trabajando en PHP (Zend Framework) para un cliente. Objective-C (iOS) para el otro.

¿El descubrimiento de Runtime es una meta realista, dado el conjunto actual de herramientas y conocimientos en la comunidad de desarrolladores? Puedo escribir a mi cliente para tratar todos los URI de una manera opaca, pero la forma de hacerlo de la manera más eficiente es una pregunta, especialmente sobre conexiones de bajo ancho de banda. De todos modos, los URI son solo una parte de la ecuación. ¿Qué pasa con las plantillas de enlaces en el contexto de tiempo de ejecución? ¿Qué hay de comunicar qué métodos son compatibles, además de realizar muchas solicitudes de OPCIONES?

Este es definitivamente un hueso duro de roer. En Google, hemos implementado nuestro Servicio de Descubrimiento en el que están compiladas todas nuestras nuevas API. La versión TL; DR genera una especificación similar a un esquema JSON que nuestros clientes pueden analizar, muchos de ellos dinámicamente.

El resultado es una actualización SDK más fácil para el desarrollador y un mantenimiento fácil / mejor para nosotros.

De ninguna manera la solución perfecta, pero a muchos de nuestros desarrolladores parece gustarles.

Vea el link para más detalles (y asegúrese de ver el video).

Fascinante. Lo que estás describiendo es básicamente el principio HATEOAS. ¿Qué es HATEOAS preguntas? Lea esto: http://en.wikipedia.org/wiki/HATEOAS

En términos simples, HATEOAS significa enlace siguiente. Este enfoque desacopla a su cliente de URL específicas y le brinda la flexibilidad de cambiar su API sin romper a nadie.

Uno de los requisitos que debe cumplir antes de que pueda llamar a una API ''RESTful'' es que debería ser posible escribir una aplicación de cliente genérico sobre esa API. Con el cliente genérico, un usuario debería poder acceder a todas las funcionalidades de la API. Un cliente genérico es una aplicación cliente que no supone que ningún recurso tenga una estructura específica más allá de la estructura definida por el tipo de medio. Por ejemplo, un navegador web es un cliente genérico que sabe cómo interpretar HTML, incluidos formularios HTML, etc.

Ahora, supongamos que tenemos una API HTTP / JSON para una tienda web y queremos construir un cliente HTML / CSS / JavaScript que brinde a nuestros clientes una excelente experiencia de usuario. ¿Sería una opción realista dejar que ese cliente sea una aplicación cliente genérica ? No. Queremos proporcionar una apariencia específica para cada elemento de datos específico y cada estado de aplicación específico. No queremos incluir todo el conocimiento sobre estos aspectos específicos de la presentación en la API; por el contrario, el cliente debe definir la apariencia y la API solo debe llevar los datos. Esto implica que el cliente tiene un acoplamiento codificado de elementos de recursos específicos a diseños específicos e interacciones del usuario.

¿Es este el final de HATEOAS y por lo tanto el final de REST? Sí y no

Sí , porque si codificamos el conocimiento sobre la API en el cliente, perdemos el beneficio de HATEOAS: los cambios en el servidor pueden dañar al cliente.

No , por dos razones:

  1. Ser "RESTful" es una propiedad de la API, no del cliente. Mientras sea posible, en teoría , construir un cliente genérico que ofrezca todas las capacidades de la API, la API se puede llamar RESTful. El hecho de que los clientes no obedezcan las reglas no es culpa de la API. El hecho de que un cliente genérico tenga una experiencia de usuario pésima no es un problema. ¿Por qué es importante saber que es posible tener un cliente genérico si no tenemos ese cliente genérico? Esto me lleva a la segunda razón:
  2. Una API RESTful ofrece a los clientes la opción de elegir qué tan genéricos quieren ser, es decir, qué tan resistentes a los cambios del lado del servidor quieren ser. Los clientes que necesitan proporcionar una excelente experiencia de usuario aún pueden ser resistentes a los cambios de URI, a los cambios en los valores predeterminados y más. Los clientes que realizan trabajos por lotes sin interacción del usuario pueden ser resistentes a otros tipos de cambios.

Si está interesado en ejemplos prácticos, revise mi artículo JAREST . La última sección es sobre HATEOAS. Verá que con JAREST, incluso los clientes altamente interactivos y visualmente atractivos pueden ser bastante resistentes a los cambios en el servidor, aunque no al 100%.

Usted escribe:

Para hacer que la API sea muy eficiente, parece que se necesita mucha plantilla de enlace para los parámetros de consulta, lo que hace que la información fuera de banda vuelva a aparecer.

Si esa plantilla de enlace se proporciona en la solicitud anterior, entonces no hay información fuera de banda. Por ejemplo, un formulario de búsqueda HTML utiliza plantillas de enlaces ( /search?q=%@ ) para generar una URL ( /search?q=hateoas ), pero el cliente no conoce nada (el navegador web) que no sea cómo usar formularios HTML. y GET .