È che API REST davvero RPC? Roy Fielding sembra pensare così
https://stackoverflow.com/questions/1164154
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianDomanda
Una grande quantità di quello che ho pensato che sapevo di REST è apparentemente sbagliato - e io non sono il solo. Questa domanda ha una lunga lead-in, ma sembra essere necessario perché l'informazione è un po 'sparso. La domanda effettiva arriva alla fine se sei già familiarità con questo argomento.
A partire dal primo comma REST API must di Roy Fielding essere ipertestuale-driven , è abbastanza chiaro che crede che il suo lavoro è stato ampiamente male interpretato:
mi sto frustrato per il numero di persone che chiedono qualsiasi interfaccia basata su HTTP API REST. L'esempio di oggi è il SocialSite API REST . Questo è RPC. Si urla RPC. C'è così tanto di accoppiamento in mostra che dovrebbe essere data una valutazione X.
Fielding prosegue elencando diversi attributi di un API REST. Alcuni di loro sembrano andare contro sia pratica comune e consiglio comune su SO e altri forum. Ad esempio:
-
Un'API REST deve essere inserito senza alcuna conoscenza preliminare al di là del primo URI (segnalibro) e un insieme di tipi di supporto standardizzati che sono appropriati per i destinatari (ad esempio, dovrebbe essere compreso da qualsiasi client che potrebbe utilizzare il API). ...
-
Un'API REST non deve definire i nomi delle risorse fissi o gerarchie (un accoppiamento evidente di client e server). ...
-
Un'API REST deve spendere quasi tutto il suo sforzo descrittivo nella definizione del tipo di supporto (s) utilizzato per rappresentare le risorse e guidare lo stato dell'applicazione, o nella definizione di nomi di relazioni estesi e / o ipertesti abilitata mark-up per esistente tipi di supporti standard. ...
L'idea di "ipertesto" svolge un ruolo centrale - molto più di quanto la struttura URI o quello HTTP verbi significano. "Ipertesto" è definito in uno dei commenti:
Quando ho [Fielding] dico ipertesti, intendo la presentazione simultanea di informazioni e controlli in modo tale che l'informazione diventa l'affordance attraverso il quale l'utente (o automa) ottiene scelte e seleziona le azioni. Hypermedia è solo un espansione sul quale testo significa includere ancore temporali all'interno di un flusso multimediale; maggior parte dei ricercatori sono scesi la distinzione.
L'ipertesto non ha bisogno di essere HTML in un browser. Le macchine possono seguire i link quando capiscono i tipi di formato e di associazione dati.
sto cercando di indovinare a questo punto, ma i primi due punti di cui sopra sembrano suggerire che la documentazione API per una risorsa Foo che appare come il seguente porta ad accoppiamento stretto 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
Al contrario, un agente dovrebbe essere costretto a scoprire le URI per tutti Foos, ad esempio, l'emissione di una richiesta GET contro / foos. (Tali URI può rivelarsi seguire lo schema di cui sopra, ma non è questo il punto.) La risposta utilizza un tipo di supporto che è in grado di trasmettere come accedere ogni elemento e ciò può essere fatto con esso, dando origine al terzo punto sopra . Per questo motivo, documentazione API dovrebbe concentrarsi su che spiega come interpretare l'ipertesto contenuta nella risposta.
Inoltre, ogni volta che un URI a una risorsa Foo è richiesta, la risposta contiene tutte le informazioni necessarie per un agente per scoprire come procedere, ad esempio, l'accesso alle risorse collegate e controllanti attraverso i loro URI, o agendo dopo la creazione / eliminazione di una risorsa.
La chiave per l'intero sistema è che la risposta consiste di ipertesto contenuta in un tipo di supporto che si trasmette alle opzioni dell'agente per procedere. Non è a differenza del modo in cui un browser funziona per gli esseri umani.
Ma questa è solo la mia ipotesi migliore in questo particolare momento.
Fielding ha registrato un follow-up in cui ha risposto alle critiche che la sua discussione è stata troppo astratto, privo di esempi, e ricco di gergo:
Altri cercheranno di decifrare quello che ho scritto in modi che sono più direttamente o applicabile a una certa preoccupazione pratica oggi. Io probabilmente non lo farà, perché io sono troppo occupato alle prese con l'argomento successivo, la preparazione per una conferenza, scrivere un altro standard, un viaggio in qualche luogo lontano, o semplicemente fare le piccole cose che mi permetta di sentire che ho Ho guadagnato il mio stipendio.
Quindi, due semplici domande per gli esperti REST là fuori con una mentalità pratica: come si fa a interpretare ciò che Fielding sta dicendo e come si fa a mettere in pratica quando si documenta / attuazione REST API
Modifica: questa domanda è un esempio di quanto sia difficile può essere quello di imparare qualcosa se non si dispone di un nome per quello che stai parlando. Il nome in questo caso è "Hypermedia come il motore di Application Stato" (hateoas).
Soluzione
Credo che la vostra spiegazione copre la maggior parte di esso. URI sono identificatori opachi che dovrebbero, per la maggior parte, non possono essere comunicati al di là del segnalibro URI che viene utilizzato dal programma utente per accedere all'applicazione.
Per quanto riguarda la documentazione, questa domanda è stato fatto un bel paio di volte. Documentare il tipo di supporto, insieme con il collegamento ipertestuale controlla che esso contiene (collegamenti e forme), e il modello di interazione, se lo si desidera (vedi AtomPub).
Se si documentare gli URI o come costruire loro, si sta facendo male.
Altri suggerimenti
La sua interpretazione sembra corretto a me. Credo che i vincoli di Fielding può essere applicata praticamente.
Mi piacerebbe davvero vedere qualcuno pubblicare alcuni buoni esempi di come documentare un'interfaccia REST. Ci sono tanti esempi poveri, ha alcuni tra quelli validi per puntare agli utenti di sarebbe molto prezioso.
Sono stato alla ricerca di un buon esempio di un API scritta in seguito alla hateoas e avuto difficoltà a trovarne uno (ho trovato sia l'API SunCloud e roba AtomPub difficile da applicare ad una situazione "normale" API). Così ho provato a fare un esempio realistico sul mio blog che seguì il consiglio Roy Fielding su ciò che significa essere un'implementazione corretta REST. Ho trovato molto difficile a venire con l'esempio, nonostante il fatto che è abbastanza semplice in linea di principio (solo confusione quando si lavora con un'API rispetto a una pagina web). Ho quello che Roy stava prendendo questione con e sono d'accordo, è solo un cambiamento di mentalità per implementare correttamente per un'API.
Date un'occhiata: API Esempio di utilizzo di Riposo
L'unica eccezione a dando istruzioni su come costruire URI è che è consentito inviare un modello di URI nella risposta ipertestuale, con campi da sostituire automaticamente dal client, utilizzando altri campi nella ipertestuale. Questo di solito non finire per salvare la larghezza di banda anche se da quando la compressione gzip gestirà le parti ripetute URI abbastanza bene per non perdere tempo con questo.
Alcune buone discussioni su REST e le relative hateoas:
Per chi fosse interessato, ho trovato un esempio dettagliato di hateoas in pratica nelle API Sole Nube .
La cosa che la maggior parte delle persone ottenere sbagliato è che (almeno credo) nel mondo REST non si documentare il "interfaccia di riposo", quello che si documento è un tipo di supporto, in modo indipendente del server o del servizio.
assolutamente corretto. Mi piacerebbe Nota Oltre che che i modelli di URI sono perfettamente bene all'interno di un'applicazione RESTful a condizione che i modelli sono da documenti ricevuti dal server (OpenSearch essere un esempio adatto). Per i modelli di URI, documentare dove sono in uso e quali sono i segnaposti attesi nel modello sono, ma non i modelli stessi. Un po 'al contrario di quanto detto Wahnfrieden, questa non è un'eccezione.
Per esempio, al mio lavoro che abbiamo un sistema di gestione del dominio interno, e il documento di servizio specifica due modelli URI: una per la produzione di una migliore ipotesi URI di una risorsa di dominio, e un altro per la costruzione di un URI per interrogare la disponibilità del dominio. E 'ancora possibile sfogliare la collezione domini di capire cosa l'URI di un determinato dominio, ma dato l'immenso numero di domini da essa gestiti, questo non sarebbe fattibile per il cliente, in modo da dare loro un modo di indovinare ciò che il URI di una risorsa di dominio potrebbe essere è una grande vittoria in termini di facilità di implementazione dal punto di vista del cliente, e la larghezza di banda dal server del.
On alla tua domanda: La nostra documentazione normativa è esposto risorse, l'effetto di vari metodi su tali risorse, e le tipologie di mezzi di rappresentanza utilizzati e le loro schemi, e che tipo di risorse gli URI in quelle representions puntano a
Abbiamo anche non-normativo documentazione (informativa) che ha collegato ad esso un disclaimer di non leggere troppo negli URI menzionati nel documento, che fornisce esempi di interazioni tipiche client-server. Ciò pone la documentazione piuttosto astratto normativo in termini concreti.
Credo che il numero di anni che il riposo è stato lì fuori ora, tecnologi sono venuti a patti con il concetto di una risorsa e di ciò che è veramente o no è riposante.
Secondo il modello di maturità Richardson, ci sono 4 livelli (0-3) che definiscono come RESTful API è la vostra, con 3 significato un'API RESTful veramente, proprio come Roy Fielding voleva che fosse.
Il livello 0 è quando si dispone di un punto di ingresso URI -. Come SOAP
Livello 1 significa l'API è in grado di distinguere tra le diverse risorse, e ha più di uno i punti di ingresso -. Ancora profuma di SOAP
Livello 2 è quando si utilizza verbi HTTP - GET, POST, DELETE in primo luogo. Questo è il livello al quale resto viene in realtà in foto.
Al livello 3, di iniziare a utilizzare i comandi ipermediali per rendere il vostro API davvero RESTful.
Links consigliati per ulteriori letture:
Supponiamo GET /foos/createForm è invocato per ottenere i valori campi modulo per i quali deve essere fornito quando andiamo a creare POST /foos. Ora questa particolare URL cioè il 1 utilizzato per creare foos dovrebbe essere menzionato all'interno della risposta per GET /foos/createForm come collegamento presentare un'azione in base alla proposta di Fielding, giusto?
Allora qual è il vantaggio di azioni di mappatura a ben noti i verbi HTTP per azioni, "Convenzione di oltre il codice / config" cosa è annullato.
