¿Qué ofrece HATEOAS para la detección y el desacoplamiento, además de la capacidad de cambiar la estructura de su URL más o menos libremente?

Creo que tus instintos son en gran parte correctos; esos beneficios proclamados no son realmente tan buenos, ya que para cualquier aplicación web no trivial, los clientes tendrán que preocuparse por la semántica de lo que están haciendo y la sintaxis.

¡Pero eso no significa que no debas hacer que tu aplicación siga los principios de HATEOAS!

¿Qué significa HATEOAS realmente ? Significa estructurar su aplicación para que, en principio, sea como un sitio web , y que todas las operaciones que desee realizar puedan descubrirse sin tener que descargar un esquema complejo. . (Los esquemas WSDL sofisticados pueden abarcar todo, pero en el momento en que lo hacen, han superado la capacidad de prácticamente todos los programadores para entender, y mucho menos escribir. Puede ver HATEOAS como una reacción ante tal complejidad.)

HATEOAS no solo significa enlaces enriquecidos. Significa utilizar los mecanismos de error del estándar HTTP para indicar más exactamente qué fue lo que salió mal; no tienes que responder simplemente con "¡waaah! no ”y, en cambio, puede proporcionar un documento que describa lo que realmente estaba mal y lo que el cliente podría hacer al respecto. También significa admitir cosas como solicitudes de OPCIONES ( la forma estándar de permitir que los clientes descubran qué métodos HTTP pueden usar) y negociación de tipo de contenido para que el formato de la respuesta se pueda adaptar a una forma que los clientes puedan manejar. Significa poner texto explicativo (o, más probablemente, enlaces a él) para que los clientes puedan ver cómo usar el sistema en casos no triviales si no lo saben; El texto explicativo puede ser legible para el ser humano o puede ser legible por máquina (y puede ser tan complejo como desee). Por último, significa que los clientes no sintetizan enlaces (excepto los parámetros de consulta); los clientes solo usarán un enlace si se lo dices.

Tienes que pensar en que un usuario navegue el sitio (que puede leer JSON o XML en lugar de HTML, por lo que es un poco extraño) con una memoria excelente para enlaces y un conocimiento enciclopédico del Estándares HTTP, pero por lo demás no se sabe qué hacer.

Y, por supuesto, puede usar la negociación de tipo de contenido para presentar un cliente HTML (5) / JS que les permitirá usar su aplicación, si eso es lo que su navegador está preparado para aceptar. Después de todo, si su API RESTful es buena, ¿debería ser "trivial" implementarla?

Lo importante es que HATEOAS debe venir con un segundo pilar que define qué es una API RESTful: el tipo de medio estandarizado. Roy se presentó a sí mismo

  

Una API REST debería dedicar casi todo su esfuerzo descriptivo a la definición de los tipos de medios utilizados para representar los recursos ".

Con un tipo de medio estandarizado que define la transición explícitamente y el hipertexto para apuntar los recursos entre sí, puede crear un gráfico de recursos que puede tomar cualquier forma sin afectar a ningún cliente. Al igual que el trabajo web, en realidad: tiene un enlace entre el documento y el documento está escrito en HTML que define cómo seguir esos enlaces. <a href> es un GET, <form> es GET o POST (y define la plantilla de URL para usar en el caso de GET), <link type="text/css"> es GET ... etc. Así es como los navegadores pueden navegar por páginas HTML estructuradas arbitrarias y Web.

Todos los puntos que hiciste

  

• qué parámetros de consulta puede usar y sus posibles valores
  
• la estructura de JSON / XML / cualquier documento que necesite enviar en sus solicitudes POST / PATCH / etc
  
• la estructura de la respuesta enviada por el servidor
  
• los posibles errores que pueden ocurrir
  

Son puntos que deben ser resueltos por la definición de su tipo de medio estandarizado . Por supuesto, esto es mucho más difícil y no es algo en lo que la mayoría de las personas piense cuando definen una API "REST". No puede simplemente tomar sus entidades comerciales y empujar sus atributos en un documento JSON para tener una API RESTful.

Por supuesto, lo que sucedió es que REST se diluyó de alguna manera para significar "usar HTTP en lugar de complicadas cosas de SOAPY". El simple uso de HTTP y el hipertexto no es suficiente para ser RESTOS, esto es lo que la mayoría de las personas se equivoca.

No es necesario que esto sea algo malo: REST realiza sacrificios de rendimiento y facilidad de desarrollo a cambio de mantenibilidad y evolutividad a largo plazo. Fue hecho para la integración de grandes aplicaciones empresariales. Una pequeña API web con estructura JSON codificada puede ser lo que necesite. Simplemente no lo llame REST, es una API web ad-hoc, nada más. Y eso no significa que apeste, simplemente significa que no intenta seguir la restricción de REST.

Lectura adicional

• enlace
• enlace

Espero que esto ayude a aclarar un poco :)

Hay algunos formatos de Hypermedia que intentan proporcionar respuestas más completas que incluyen más información sobre qué tipo de solicitudes enviar, y no hay nada que le impida enriquecer la respuesta con más información.

Aquí hay un ejemplo del documento Siren :

{
  "class": [ "order" ],
  "properties": { 
      "orderNumber": 42, 
      "itemCount": 3,
      "status": "pending"
  },
  "entities": [
    {
      "class": [ "info", "customer" ],
      "rel": [ "http://x.io/rels/customer" ], 
      "properties": { 
        "customerId": "pj123",
        "name": "Peter Joseph"
      },
      "links": [
        { "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
      ]
    }
  ],
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        { "name": "orderNumber", "type": "hidden", "value": "42" },
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ],
  "links": [
    { "rel": [ "self" ], "href": "http://api.x.io/orders/42" },
    { "rel": [ "previous" ], "href": "http://api.x.io/orders/41" },
    { "rel": [ "next" ], "href": "http://api.x.io/orders/43" }
  ]
}

Como puede ver, en el mensaje se proporciona información sobre cómo llamar a actions relacionado, y luego, al interpretar esta información, el cliente se vuelve más resistente al cambio.

Se vuelve particularmente poderoso si rel s son URI que se pueden buscar, en lugar de un vocabulario fijo.

¿Dónde leyó que "la documentación ya no es necesaria" para los servicios de HATEAOS? Como usted dice, todavía necesita documentar la semántica de los enlaces. Sin embargo, con HATEOAS no necesita documentar y, por lo tanto, mantener para siempre, la estructura de la mayoría de los URI.

HATEOAS permite a un implementador de servicios modificar y escalar la implementación de manera significativa y eficiente sin cambiar un pequeño conjunto de URI de los que depende el cliente. Es más fácil mantener un pequeño número de puntos de entrada sin cambios que un conjunto grande. Por lo tanto, la reducción del número de puntos de entrada públicos al servicio y la provisión dinámica de enlaces a sub-recursos (HATEOAS) en realidad admite "Cool URI no cambian" mejor que los servicios que no son HATEOAS.