Come si dovrebbero fornire collegamenti nel servizio RESTful usando una rappresentazione di dati non XML?

Question

Ultimamente ho letto molto su come implementare veramente WS RESTful. Un sacco di persone si sono collegate all'articolo here che dettaglia diversi vincoli che gli implementatori dovrebbero tenere a mente se vogliono finire con servizi conformi al concetto REST.

Mentre il post è chiaramente importante, sfortunatamente è abbastanza difficile da capire per noi comuni mortali e varie persone hanno provato a decipher it. Forse la migliore spiegazione che ho trovato può essere trovata here, dove l'autore fornisce un esempio concreto del perché molte API "RESTful" in circolazione oggi non sono affatto RESTful e mostra come la situazione può essere corretta.

La sua proposta si basa pesantemente sull'uso di collegamenti di incorporamento all'interno delle rappresentazioni delle risorse esposte e ha molto senso: posso seguire chiaramente la logica e vorrei impiegare tali tecniche da solo in un insieme di servizi che sto progettando tuttavia, ho un problema che non sono sicuro di come dovrei risolvere: ovvero come si dovrebbero fornire tali collegamenti se le rappresentazioni dei dati utilizzate non sono XML, ma qualcosa come JSON?

Tutto ciò che l'autore dice ha perfettamente senso nel mondo XML ma non riesco a vedere chiaramente come questo possa essere riapplicato ad altre rappresentazioni di contenuti?

Molto interessato ad ascoltare le opinioni di altre persone e vedere come le persone possono aver affrontato questo problema nelle proprie API REST non basate su XML.

[modifica]: da quando ho scritto questa domanda ho trovato il seguente usefullinks. Ci vuole molto per rispondere alla mia domanda, ma sono comunque interessato alle opinioni degli altri.

Answer 1

Ho lottato con questa stessa domanda per molto tempo. Sono giunto a due conclusioni: a) re-inventare XML con una sintassi diversa (in pratica ciò che questi link propongono), o b) decidere su alcune semplici convenzioni fisse.

Sono andato con b. Per l'API a cui sto lavorando ora, ci sono due modi per specificare un collegamento come dove è possibile recuperare le informazioni.

Il primo è che il valore viene sempre considerato come un URI in alcuni casi. L'applicazione conosce un URI perché è quello che il nostro tipo di supporto dice che deve essere.

{"form_type": "whatever", "validator": "http://example.com/validatorA"} 

La seconda è che i valori per una tornata strutturata può essere sia il tipico tipo standard (int, string, elenco, oggetti, ecc), o di un oggetto con il tasto "magica" __ref__. Questo fa parte del nostro modo in cui definiamo anche il tipo di media ("__" è anche illegale nei nomi delle proprietà secondo le regole della nostra app, quindi non dovrebbe mai verificarsi). È fino all'app per dereferenziare il valore a suo piacimento.

{"owner": "john", "attachment": {"__ref__": "http://..."}} 

Questo funziona per noi. La maggior parte delle volte ci interessa che il valore sia la stringa "john", e meno sul concetto astratto di "john" è una risorsa Owner (con più del semplice identificatore "john" come suo contenuto).

Per le nostre esigenze, abbiamo scambiato la semplicità e le prestazioni per espressività e correttezza REST. Nel mondo reale, non è un affare troppo grande avere informazioni fuori banda che dicono "vai a/users/$ username per maggiori informazioni" quando il risultato fornisce tutte le informazioni desiderate il 99% delle volte.

Il nostro piano - se necessario in futuro - è quello di allegare un collegamento aggiungendo un attributo __ref__.

{"owner": "john", "owner.__ref__": "http://ex.com/users/83j9io"} 

Mentre questo non è completo come i collegamenti forniti, penso che sia un ragionevole equilibrio. Sebbene mi piaccia l'idea che ogni valore possa avere un link alla sua risorsa unica e ad altri metadati (come descritto nel documento json-collections a cui ti colleghi), penso che le informazioni sarebbero estranee per la maggior parte del tempo. Un semplice elenco di valori con palloncini di dimensioni, ma è necessario conoscere l'URI, la versione, l'id, ecc. Di ciascun valore?

Introduce anche fastidiose complicazioni nel codice, dovendo digitare ".value" o ".members" (e tutta la semantica implica un ulteriore accesso) invece di essere in grado di utilizzare costrutti nativi. Questo modello ".value" è in realtà ciò che facciamo sul lato server, ed è tollerabile solo a causa dello sforzo di farli apparire come tipi di dati standard invece di wrapper.