Quanto deve essere specificato per i client che chiamano un servizio REST?

Suppongo che siamo sul lato client e il lato server implementa (almeno) un'API Livello 3 nel Modello di maturità Richardson

Quindi, le mie risposte a How much should be specified for clients calling a REST service sono quanto necessario e possibile .

Ok, è ingenuo da dire. Tuttavia, come in qualsiasi altra applicazione, durante la fase di progettazione, potremmo dover affrontare problemi come

• Risorse limitate
• Budget limitato
• Conoscenza limitata
• Le scadenze
• Requisiti funzionali e non funzionali

Il design dovrebbe considerare seriamente i problemi sopra menzionati perché è durante la progettazione dell'API quando viene deciso in che modo autonomo sarà consentito ai client.

However, what happens when that resource required a considerable amount of metadata? How does the client know what data is required and how to provide it? Does this all need to be provided to the client separately? It seems like it must have to be, the client can't magically know that information.

Qui hai introdotto i requisiti , quindi stai quasi rispondendo a te stesso. Come renderlo possibile sono i "dettagli di implementazione".

Alcuni meccanismi per fornire tali dettagli sono:

• Collegamenti a schemi e documentazione
• Informare i metodi e i formati insieme ai Collegamenti
• Uso della diversità intestazioni per comunicare metadati e comportamenti

Tuttavia, alcuni documenti sono ancora necessari. Ci sono più cose relative all'utilizzo dell'API. Ad esempio:

• Sicurezza
• Catalogo degli errori
• Frammenti

Come puoi immaginare, la progettazione e l'implementazione di ricche API REST potrebbe essere difficile e costosa. Ma ci sono molti framework e strumenti che rendono più facile. Ti consentono di concentrarti sull'attività piuttosto che sui dettagli di implementazione.

Infine, alla domanda

Are there any great public examples of a RESTful service that I could look at to help better understand this

Sì, ma come puoi indovinare (di nuovo), ciascun fornitore avrà progettato e implementato l'API di conseguenza con la sua comprensione del REST e tutte quelle cose che ho menzionato all'inizio della risposta.

Cerca su google con Good Examples of Hypermedia APIs , ho trovato il seguente link:

• Api Evangelist . È un post un po 'vecchio, ma le API menzionate sono ancora vive e mi sembrano un buon esempio di cosa potrebbe essere un'API.

  • FamilySearch ': Documento API . Ad esempio, controlla la risorsa Person . Segui l'attributo Link . Ci sono molte informazioni relative a come interagire con la risorsa a cui fa riferimento l'URI . Hanno anche SDK dove potresti vedere l'implementazione del client se sei interessato.

  • API Foxycart . Questo è un po 'meno auto-documentato rispetto al precedente, quindi puoi immaginare che il client debba codificare alcune informazioni. Ad esempio, quali metodo e formati di dati utilizzare ogni volta che il client chiama il servizio. Guarda il modello Link . Non fornisce né i metodi consentiti né i formati supportati.

  • PayPal . Consulta API delle fatture . Se non mi sono perso nessun dettaglio, questa API sembra essere da qualche parte tra i due esempi precedenti. Fornisce più metadati di Foxycart ma meno di FamilySearch .

Nonostante i libri consigliati siano fuori tema qui, se sei interessato ai progetti di API REST, potrebbe interessarti Progettazione API REST Regolamento. L'autore ha come obiettivo un linguaggio modello (WRML) per la progettazione di API. Ho imparato molto sul design REST e API leggendo il libro. Ma, se lo leggi, fallo con discrezione. Ciò che l'autore chiama regole può o non può essere regole standard . Lascia una finestra aperta per migliorare. Mantieni la tua mentalità aperta e adatta i tuoi progetti alle tue esigenze e necessità. Sempre.

È necessaria qualche conoscenza precedente, sì, ma la maggior parte lo sai già. Ad esempio:

• il tuo cliente sa come effettuare chiamate su HTTP (S)? Se sì, allora sai come parlare con qualsiasi servizio REST esposto su HTTP (S).
• il tuo cliente comprende gli URI? Se sì, allora sa come identificare le risorse del servizio REST.
• il tuo cliente comprende JSON o XML? Se sì, il tuo client sa come analizzare le risposte del servizio REST.

Questo ti consente di parlare al servizio. Ma come fai a capire cosa sta "dicendo"?

Dal tipo di supporto . Il tipo di media descrive il modello di dati (le risorse), le relazioni che hanno, ecc. Questa è la "lingua" che i clienti devono parlare. Senza capire il tipo di media non si capisce il servizio. Tutto ciò è documentazione che il tuo cliente ha bisogno di sapere. Qualsiasi altra documentazione è solo un aiuto extra.

Infine, hypermedia consente un'API flessibile. Rispetto a SOAP, ad esempio, in REST la tua API è più dinamica (cioè non ha un contratto statico) e ciò consente una più facile evoluzione dell'API senza rompere i client esistenti.

Oracle: quando non sei sicuro di come fare qualcosa con REST, come faresti con un sito web.

what happens when that resource required a considerable amount of metadata? How does the client know what data is required and how to provide it?

Quindi, come faresti con un sito web? L'utente caricherà l'endpoint di base e guarderà attorno nella rappresentazione di quella risorsa per il collegamento che desidera. Farebbero clic sul collegamento e la rappresentazione di tale risorsa sarebbe una forma, con etichette sui campi per comunicare il significato semantico. L'utente compila queste forme e la invia e quell'invio produce una rappresentazione di un'altra forma (hai detto un lotto di metadati), molto simile alla prima, e infine arriviamo all'ultimo modulo. Quando l'utente lo invia, il server controlla i dati forniti e modifica il proprio stato.

Si noti che qui c'è una separazione: il tipo di media (HTML) comunica collegamenti e moduli al client, che sa come analizzarli e presentarli. La semantica di tali collegamenti e moduli è indicata nella rappresentazione HTML e indirizza l'utente.

In una macchina API, il design di base è lo stesso; la macchina ha bisogno di capire il protocollo (quale link seguire, come lavorare attraverso più forme, e così via), e ha bisogno di capire la semantica (come mappare le informazioni nella rappresentazione ad una comprensione comune). Questo di solito è fatto fuori banda (relazioni di collegamento definite da schemi comuni).

Per gestire l'estensibilità, ci si assicura che il server fornisca i valori predefiniti (in modo che i client esistenti possano ignorare nuovi campi che non capiscono) e si assicura che i client non insistano su campi specifici (in modo che il server possa riordina o rimuovi una semantica).

A calling application needs to know, for example, that it was want to go to the "create" URI and do a PUT there to add a resource.

Ora, per essere onesti, "PUT" non è così ben compreso, perché non è supportato in HTML. Per capire la semantica di PUT, è necessario pensare in termini di caso d'uso originale, che era la pubblicazione remota.

Il gioco di base è lo stesso: collegamenti ipermediali che portano il cliente nella giusta posizione. Il client può utilizzare OPTIONS per stabilire che la modifica remota è supportata. In questo modo il client può caricare la rappresentazione, apportarvi modifiche e inserirla nel percorso dal quale è stata caricata.

All'interno della rappresentazione della risorsa stessa, il gioco è molto simile a prima: il client e il server devono concordare il tipo di supporto e il client deve capire l'inserimento, eliminare e modificare i meccanismi di quel tipo, e i segnali semantici comuni usati.

Molti dei vincoli che vorrete avere nella vostra rappresentazione saranno simili ai vincoli che volete nella messaggistica con versione. Il eBook di Greg Young può esserti d'aiuto.