Molto di quello che pensavo di sapere su REST è apparentemente sbagliato e non sono solo. Questa domanda ha una lunga introduzione, ma sembra necessaria perché le informazioni sono un po 'sparse. La vera domanda arriva alla fine se hai già familiarità con questo argomento.
Dal primo paragrafo delle API REST di Roy Fielding devono essere guidate da ipertesto , è abbastanza chiaro che crede che il suo lavoro sia stato ampiamente interpretato male:
Sono frustrato dal numero di persone che chiamano qualsiasi interfaccia basata su HTTP un'API REST. L'esempio di oggi è l' API REST di SocialSite . Questo è RPC. Urla RPC. C'è così tanto accoppiamento in mostra che dovrebbe essere valutato X.
Fielding prosegue elencando diversi attributi di un'API REST. Alcuni di loro sembrano andare contro sia la pratica comune che i consigli comuni su SO e altri forum. Per esempio:
Un'API REST deve essere inserita senza alcuna conoscenza preliminare oltre l'URI iniziale (segnalibro) e un set di tipi di media standardizzati appropriati per il pubblico previsto (cioè, che dovrebbero essere compresi da qualsiasi client che potrebbe utilizzare l'API). ...
Un'API REST non deve definire nomi o gerarchie di risorse fisse (un ovvio accoppiamento di client e server). ...
Un'API REST dovrebbe dedicare quasi tutto il suo sforzo descrittivo alla definizione dei tipi di media utilizzati per rappresentare le risorse e guidare lo stato dell'applicazione, o nella definizione di nomi di relazione estesa e / o markup abilitato per ipertesto per i tipi di media standard esistenti. ...
L'idea di "ipertesto" gioca un ruolo centrale, molto più della struttura URI o del significato dei verbi HTTP. "Hypertext" è definito in uno dei commenti:
Quando io [Fielding] dico ipertesto, intendo la presentazione simultanea di informazioni e controlli in modo tale che l'informazione diventi l'affordance attraverso la quale l'utente (o l'automa) ottiene scelte e seleziona azioni. L'ipermedia è solo un'espansione di ciò che il testo significa includere ancore temporali all'interno di un flusso multimediale; la maggior parte dei ricercatori ha abbandonato la distinzione.
Non è necessario che l'ipertesto sia HTML su un browser. Le macchine possono seguire i collegamenti quando comprendono il formato dei dati e i tipi di relazione.
Immagino a questo punto, ma i primi due punti sopra sembrano suggerire che la documentazione API per una risorsa Foo che assomiglia alla seguente porta a uno stretto accoppiamento tra client e server e non ha posto in un sistema RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Invece, un agente dovrebbe essere costretto a scoprire gli URI per tutti i Foos, ad esempio, inviando una richiesta GET contro / foos. (Questi URI possono risultare seguire lo schema sopra, ma non è questo il punto.) La risposta utilizza un tipo di media che è in grado di comunicare come accedere a ciascun elemento e cosa si può fare con esso, dando origine al terzo punto sopra . Per questo motivo, la documentazione API dovrebbe concentrarsi sulla spiegazione di come interpretare l'ipertesto contenuto nella risposta.
Inoltre, ogni volta che viene richiesto un URI a una risorsa Foo, la risposta contiene tutte le informazioni necessarie affinché un agente scopra come procedere, ad esempio accedendo alle risorse associate e padre tramite i loro URI, o agendo dopo la creazione / cancellazione di una risorsa.
La chiave dell'intero sistema è che la risposta consiste in un ipertesto contenuto in un tipo di supporto che a sua volta trasmette all'agente le opzioni per procedere. Non è diverso dal modo in cui funziona un browser per gli esseri umani.
Ma questa è solo la mia ipotesi migliore in questo particolare momento.
Fielding ha pubblicato un seguito in cui ha risposto alle critiche secondo cui la sua discussione era troppo astratta, priva di esempi e ricca di gergo:
Altri cercheranno di decifrare ciò che ho scritto in modi più diretti o applicabili a qualche preoccupazione pratica di oggi. Probabilmente non lo farò, perché sono troppo impegnato ad affrontare l'argomento successivo, a prepararmi per una conferenza, a scrivere un altro standard, a viaggiare in qualche luogo lontano o semplicemente a fare le piccole cose che mi fanno sentire di aver guadagnato il mio stipendio.
Quindi, due semplici domande per gli esperti REST là fuori con una mentalità pratica: come interpreti ciò che Fielding sta dicendo e come lo metti in pratica durante la documentazione / implementazione delle API REST?
Modifica: questa domanda è un esempio di quanto possa essere difficile imparare qualcosa se non hai un nome per ciò di cui stai parlando. Il nome in questo caso è "Hypermedia as the Engine of Application State" (HATEOAS).