rest - specifically - ventajas de hateoas
¿Esa API REST es realmente RPC? Roy Fielding parece pensar así (9)
Una gran cantidad de lo que pensé que sabía sobre REST aparentemente está mal, y no estoy solo. Esta pregunta tiene una larga introducción, pero parece ser necesaria porque la información está un poco dispersa. La pregunta real llega al final si ya está familiarizado con este tema.
Desde el primer párrafo de REST de Roy Fielding, las API deben estar basadas en hipertexto , es bastante claro que él cree que su trabajo está siendo ampliamente malinterpretado:
Me siento frustrado por la cantidad de personas que llaman a cualquier interfaz basada en HTTP una API REST. El ejemplo de hoy es la API REST SocialSite . Eso es RPC. Grita RPC. Hay tanto acoplamiento en la pantalla que debería tener una clasificación X.
Fielding continúa para enumerar varios atributos de una API REST. Algunos de ellos parecen ir en contra de la práctica común y el consejo común en SO y otros foros. Por ejemplo:
Se debe ingresar una API REST sin conocimiento previo más allá del URI inicial (marcador) y un conjunto de tipos de medios estandarizados que sean apropiados para la audiencia prevista (es decir, que se espera sean entendidos por cualquier cliente que pueda usar la API). ...
Una API REST no debe definir nombres de recursos fijos o jerarquías (un acoplamiento obvio de cliente y servidor). ...
Una API REST debería dedicar casi todo su esfuerzo descriptivo a definir los tipos de medios utilizados para representar los recursos y dirigir el estado de las aplicaciones, o al definir nombres de relaciones extendidas y / o márgenes habilitados para hipertexto para los tipos de medios estándar existentes. ...
La idea de "hipertexto" juega un papel central, mucho más que la estructura URI o lo que significan los verbos HTTP. "Hipertexto" se define en uno de los comentarios:
Cuando [Fielding] digo hipertexto, me refiero a la presentación simultánea de información y controles, de modo que la información se convierte en la oportunidad a través de la cual el usuario (o autómata) obtiene opciones y selecciona acciones. Hypermedia es solo una expansión de lo que significa texto para incluir anclajes temporales dentro de un flujo de medios; la mayoría de los investigadores han abandonado la distinción.
El hipertexto no necesita ser HTML en un navegador. Las máquinas pueden seguir enlaces cuando entienden el formato de datos y los tipos de relación.
Estoy adivinando en este punto, pero los dos primeros puntos parecen sugerir que la documentación de la API para un recurso de Foo que se parece a lo siguiente conduce a un estrecho acoplamiento entre el cliente y el servidor y no tiene cabida en un sistema RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
En cambio, un agente debe verse obligado a descubrir los URI para todos los Foos, por ejemplo, emitiendo una solicitud GET contra / foos. (Esos URI pueden seguir el patrón anterior, pero eso no viene al caso.) La respuesta utiliza un tipo de medios que es capaz de transmitir cómo acceder a cada elemento y qué se puede hacer con él, dando lugar al tercer punto anterior . Por esta razón, la documentación de la API debe enfocarse en explicar cómo interpretar el hipertexto contenido en la respuesta.
Además, cada vez que se solicita un URI a un recurso de Foo, la respuesta contiene toda la información necesaria para que un agente descubra cómo proceder, por ejemplo, accediendo a los recursos asociados y padres a través de sus URI, o tomando medidas después de la creación / eliminación de un recurso.
La clave para todo el sistema es que la respuesta consiste en un hipertexto contenido en un tipo de medio que transmite a las opciones del agente para proceder. No se diferencia de la forma en que un navegador funciona para los humanos.
Pero esta es solo mi mejor estimación en este momento en particular.
Fielding publicó un follow-up en el que respondió a las críticas de que su discusión era demasiado abstracta, carente de ejemplos y rica en jerga técnica:
Otros tratarán de descifrar lo que he escrito de manera más directa o aplicable a alguna preocupación práctica de hoy. Probablemente no, porque estoy demasiado ocupado lidiando con el siguiente tema, preparándome para una conferencia, escribiendo otro estándar, viajando a un lugar distante, o simplemente haciendo las pequeñas cosas que me hacen sentir que he ganado mi cheque de pago.
Entonces, dos preguntas simples para los expertos REST con una mentalidad práctica: ¿cómo interpretas lo que dice Fielding y cómo lo pones en práctica al documentar / implementar API REST?
Editar: esta pregunta es un ejemplo de lo difícil que puede ser aprender algo si no tiene un nombre para lo que está hablando. El nombre en este caso es "Hipermedia como motor del estado de la aplicación" (HATEOAS).
Absolutamente correcto. Además, señalaría que las plantillas de URI están perfectamente bien dentro de una aplicación RESTful, siempre que los patrones procedan de documentos recibidos del servidor (OpenSearch es un ejemplo adecuado). Para las plantillas de URI, documente dónde se están utilizando y cuáles son los marcadores de posición esperados en la plantilla, pero no las plantillas en sí. Ligeramente contrario a lo que dijo Wahnfrieden, esta no es una excepción.
Por ejemplo, en mi trabajo tenemos un sistema interno de administración de dominio, y el documento de servicio especifica dos plantillas URI: una para producir un URI mejor para un recurso de dominio y otra para construir un URI para consultar la disponibilidad del dominio. Todavía es posible navegar por la colección de dominios para descubrir cuál es el URI de un dominio determinado, pero dado el inmenso número de dominios que administra, esto no sería factible para el cliente, por lo que les da una manera de adivinar qué El URI de un recurso de dominio podría ser una gran ganancia en términos de facilidad de implementación desde la perspectiva del cliente y ancho de banda del servidor.
A su pregunta: nuestra documentación normativa es recursos expuestos, el efecto de varios métodos sobre esos recursos, y los tipos de medios de representación utilizados y sus esquemas, y qué tipo de recursos señalan los URI en esas representaciones.
También incluimos documentación no normativa (informativa) que tiene adjunta un descargo de responsabilidad para no leer demasiado en los URI mencionados en el documento, que proporciona ejemplos de interacciones típicas cliente-servidor. Esto pone la documentación normativa bastante abstracta en términos concretos.
Creo que a lo largo de la cantidad de años que REST ha estado allí ahora, los tecnólogos han llegado a un acuerdo con el concepto de Recurso y lo que realmente es o no RESTANTE.
De acuerdo con el Modelo de Madurez de Richardson, hay 4 niveles (0-3) que definen qué tan RESTful es su API, y 3 significa una API RESTful verdadera, tal como Roy Fielding pretendía.
El nivel 0 es cuando tiene un URI de punto de entrada, como SOAP.
El nivel 1 significa que la API puede distinguir entre diferentes recursos y tiene más de un punto de entrada, todavía huele a SOAP.
El nivel 2 es cuando usa verbos HTTP: GET, POST, DELETE principalmente. Este es el nivel en el que REST realmente entra en la imagen.
En el Nivel 3, comienzas a usar controles de hipermedia para hacer que tu API sea realmente RESTful.
Enlaces sugeridos para lectura adicional:
Creo que tu explicación lo cubre en su mayoría. Los URI son identificadores opacos que, en su mayor parte, no deben comunicarse más allá del URI de marcador que utiliza el agente de usuario para acceder a la aplicación.
En cuanto a la documentación, esta pregunta ha sido hecha bastantes veces. Usted documenta su tipo de medio, junto con los controles de hipervínculo que contiene (enlaces y formularios), y el modelo de interacción si lo desea (vea AtomPub).
Si documenta los URI o cómo compilarlos, lo está haciendo mal.
He estado buscando un buen ejemplo de una API escrita siguiendo el HATEOAS y tuve problemas para encontrarla (encontré que las API de SunCloud y AtomPub son difíciles de aplicar a una situación de API "normal"). Así que intenté hacer un ejemplo realista en mi blog que siguiera los consejos de Roy Fieldings sobre lo que significa ser una implementación de REST adecuada. Me resulta muy difícil dar con el ejemplo, a pesar de que es bastante simple en principio (simplemente confuso cuando se trabaja con una API en lugar de una página web). Entiendo por qué Roy estaba teniendo problemas y estoy de acuerdo, es solo un cambio de mentalidad para implementar correctamente para una API.
Eche un vistazo: Ejemplo de API usando Rest
La única excepción a la instrucción sobre cómo construir URIs es que es permisible enviar una plantilla de URI en la respuesta de hipertexto, con campos que el cliente debe sustituir automáticamente, usando otros campos en el hipertexto. Esto no suele terminar ahorrando mucho ancho de banda, ya que la compresión gzip manejará las partes repetidas de los URI lo suficientemente bien como para no molestarse con esto.
Algunas buenas discusiones sobre REST y el HATEOAS relacionado:
Lo que la mayoría de la gente se equivoca es que (al menos creo) en el mundo REST no documenta su "interfaz de reposo", lo que usted documenta es un tipo de medio, independientemente de su servidor o servicio.
Para aquellos interesados, encontré un ejemplo detallado de HATEOAS en práctica en kenai.com/projects/suncloudapis/pages/Home .
Supongamos que se invoca GET /foos/createForm para obtener los valores de los campos de formulario que se deben proporcionar cuando vamos a crear POST /foos . Ahora esta URL particular, es decir, la 1 utilizada para crear foos, debe mencionarse dentro de la respuesta para GET /foos/createForm como un enlace de acción de envío de acuerdo con la proposición de Fielding, ¿no?
Entonces, ¿cuál es el beneficio de asignar acciones a los verbos conocidos de Http a las acciones? La cosa "convención sobre código / configuración" está anulada.
Tu interpretación me parece correcta. Creo que las limitaciones de Fielding se pueden aplicar de manera práctica.
Realmente me gustaría que alguien publique algunos buenos ejemplos de cómo documentar una interfaz REST. Hay muchos ejemplos pobres, algunos validos a los que los usuarios podrían ser muy valiosos.