Che cosa offre HATEOAS per la rilevabilità e il disaccoppiamento oltre alla possibilità di modificare la struttura dell'URL più o meno liberamente?

Penso che i tuoi istinti siano in gran parte corretti; quelli proclamati benefici non sono poi così grandi, come per qualsiasi applicazione web non banale che i clienti dovranno preoccuparsi della semantica di ciò che stanno facendo e della sintassi.

Ma ciò non significa che non dovresti fare in modo che la tua applicazione segua i principi di HATEOAS!

Che cosa significa veramente HATEOAS? Significa strutturare la tua applicazione in modo che sia in linea di principio come un sito web e che tutte le operazioni che potresti voler eseguire possano essere scoperte senza dover scaricare alcuni schemi complessi . (I sofisticati schemi WSDL possono coprire tutto, ma nel momento in cui lo fanno, hanno superato la capacità di praticamente ogni programmatore di capire, e tanto meno scrivere! È possibile visualizzare HATEOAS come una reazione contro tale complessità.)

HATEOAS non significa solo link ricchi. Significa utilizzare i meccanismi di errore dello standard HTTP per indicare più esattamente cosa è andato storto; non devi solo rispondere con "waaah! no "e può invece fornire un documento che descrive ciò che è effettivamente sbagliato e ciò che il cliente potrebbe fare al riguardo. Significa anche supportare cose come Richieste di OPZIONI ( il modo standard per consentire ai clienti di scoprire quali metodi HTTP possono utilizzare) e la negoziazione del tipo di contenuto in modo che il formato della risposta possa essere adattato a un modulo che i clienti possano gestire. Significa inserire testo esplicativo (o, più probabilmente, link ad esso) in modo che i clienti possano cercare come utilizzare il sistema in casi non banali se non lo sanno; il testo esplicativo potrebbe essere leggibile dall'uomo o potrebbe essere leggibile da una macchina (e può essere complesso come si desidera). Infine, significa che i client non sintetizzano i link (ad eccezione dei parametri di query); i clienti utilizzeranno un link solo se glielo hai detto.

Devi pensare di vedere il sito sfogliato da un utente (che può leggere JSON o XML invece di HTML, quindi un po 'strano) con una grande memoria per i collegamenti e una conoscenza enciclopedica del Standard HTTP, ma altrimenti nessuna conoscenza di cosa fare.

E ovviamente, puoi usare la negoziazione del tipo di contenuti per servire un client HTML (5) / JS che consentirà loro di usare la tua applicazione, se è quello che il loro browser è pronto ad accettare. Dopotutto, se la tua API RESTful è valida, dovrebbe essere "banale" implementarla su di essa?

Il punto è che HATEOAS deve venire con un secondo pilastro che definisca cos'è un'API RESTful: tipo di supporto standardizzato. Lo stesso fielding Roy ha detto

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources".

Con un tipo di supporto standardizzato che definisce la transizione in modo esplicito e l'ipertesto per indirizzare la risorsa l'un l'altro, è possibile creare un grafico delle risorse che può assumere qualsiasi forma senza rompere alcun client. Come il lavoro sul web, in realtà: hai un collegamento tra documenti, e il documento è scritto in HTML che definisce come seguire quei collegamenti. <a href> è un GET, <form> è GET o POST (e definisce il modello di url da utilizzare in caso di GET), <link type="text/css"> è GET ... ecc. In questo modo i browser possono navigare su una pagina HTML strutturata arbitraria e Web.

Tutto il punto che hai fatto

• what query parameters you can use and their possible values
• the structure of the JSON/XML/whatever documents you need to send in your POST/PATCH/etc requests
• the structure of the response sent by the server
• the possible errors that might occur

I punti devono essere indicati dalla definizione del tipo di supporto standardizzato . Certo, questo è molto più difficile, e non qualcosa a cui la maggior parte della gente pensa quando definiscono un'API "REST". Non puoi limitarti a prendere le tue entità aziendali e inserire i loro attributi in un documento JSON per avere un'API RESTful.

Ovviamente, ciò che è accaduto è che REST è stato in qualche modo diluito nel significato di "usare HTTP invece di cose SOAPy complicate". Basta usare HTTP e HyperText non è sufficiente per essere RESTful, questo è ciò che la maggior parte delle persone sbaglia.

Non è necessario questo è un aspetto negativo: REST fa sacrificare le prestazioni e la facilità di sviluppo in cambio di manutenibilità ed evolutività a lungo termine. È stato realizzato per l'integrazione di grandi aziende. Una piccola API Web con struttura JSON codificata può essere ciò di cui hai bisogno. Basta non chiamarlo REST, è una API web ad-hoc, nient'altro. E questo non significa che faccia schifo, significa solo che non prova a seguire il vincolo di REST.

Ulteriori letture

• link
• link

Spero che questo aiuto chiarisca un po ':)

Ci sono alcuni formati Hypermedia che si sforzano di fornire risposte più ricche che includono maggiori informazioni su quale tipo di richieste inviare, e non c'è nulla che ti impedisca di arricchire la risposta con ancora più informazioni.

Ecco un esempio Siren documento:

{
  "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" }
  ]
}

Come puoi vedere, le informazioni su come chiamare actions correlata sono fornite nel messaggio, e quindi interpretando queste informazioni, il client diventa più resistente ai cambiamenti.

Diventa particolarmente potente se rel s sono URI che possono essere cercati, piuttosto che da un vocabolario fisso.

Dove hai letto che "la documentazione non è più necessaria" per i servizi HATEAOS? Come dici tu, hai ancora bisogno di documentare la semantica dei link. Tuttavia, con HATEOAS non è necessario documentare e quindi conservare per sempre la struttura della maggior parte degli URI.

HATEOAS consente a un implementatore di servizi di modificare e scalare l'implementazione in modo significativo ed efficiente senza modificare un piccolo insieme di URI da cui dipende il client. È più facile mantenere un numero limitato di punti di ingresso invariato rispetto a un set di grandi dimensioni. Quindi, riducendo il numero di punti di accesso pubblici al servizio e fornendo in modo dinamico collegamenti a risorse secondarie (HATEOAS), in realtà supporta "gli URI freschi non cambiano" meglio dei servizi non HATEOAS.