Progettazione schema URI API Web

Question

Progettazione schema URI API Web

#1 da (2 voti)
#2 da (1 voti)

6

Sono nel bel mezzo della progettazione di un'API per un'applicazione di flashcard di base per scopi di apprendimento e mi chiedo se tutti voi pensate che possano esserci miglioramenti.

Nell'app, una cartella contiene cartelle e set. Un set contiene carte. La home page elenca tutti gli insiemi e le cartelle di livello superiore che ho creato (ma mai le carte). Ecco lo schema URI che ho trovato:

Questo sembra ok? Il mio obiettivo è mantenere gli URI concisi / concisi / semplici e spingere qualsiasi metadata della relazione (parentFolderId, parentSetId, ecc.) Nel corpo della richiesta. Pensieri?

clean-code api design-patterns

posta RobVious 28.03.2013 - 19:37

fonte

2 risposte

Leggi altre domande sui tag clean-code api design-patterns

Come documentare gli eventi? Come strutturare una moderna applicazione web

score 2 · Answer 1

Mi sembra che l'API sarebbe più concisa / semplice se strutturassi la tua API per riflettere la struttura gerarchica dei dati, in parte perché la struttura sarebbe autodocumentante.

Così com'è, non vedo un modo per un cliente ad es. ottenere i set in una cartella particolare; con più struttura che potresti fare:

GET /folders/100/sets

Dipende molto da cosa pensi che i tuoi clienti dovranno essere in grado di fare.

Inoltre, probabilmente supporterò OTTIENI restituendo un elenco per le richieste a un URL di raccolta come /folders , ma se non pensi che sarebbe usato per qualsiasi motivo, dovresti probabilmente vorrai restituire uno stato di 405 Method Not Allowed invece di un errore.

Oltre a questo, l'uso di POST , PUT e DELETE sembra corretto in base alle mie conoscenze.

Solo una nota: un dettaglio a volte confuso è che PUT può essere utilizzato anche per creare risorse. La differenza tra questo e POST è che, con PUT , il tuo cliente ha già l'ID risorsa e lo include nel corpo della richiesta; con POST ti aspetti che il servizio crei un ID per la risorsa. Puoi utilizzare questa differenziazione se stai utilizzando una chiave naturale per identificare una risorsa, ad es. nome utente per una risorsa utente; in questo caso useresti PUT per creare o aggiornare l'utente.

score 1 · Answer 2

Mike Partridge ha la risposta giusta sopra, ma volevo solo aggiungere.

Ecco un buon riferimento per il tipo di risposte che dovresti inviare alle tue richieste riposanti.

In particolare, dovresti restituire 404 accanto alle richieste PUT / DELETE alla raccolta (/ cartelle) e alle richieste POST all'oggetto (/ folders / id).

Inoltre, le risorse tendono ad essere annidate quando è pertinente / appropriato farlo.

Sembra che nel tuo caso le cartelle siano sempre un elemento di livello superiore, i set saranno sempre in una cartella e le carte saranno sempre in set, quindi:

/folders/:id/sets/:id/cards/:id dovrebbe essere una risorsa consentita

Ho visto questo riferimento come la convenzione di scavatura-deep-path-and-backspace dove è facile spostarsi nell'albero semplicemente spostando lo schermo all'ultima /

L'ultimo link che ho fornito ha molti URL di esempio che potresti usare in uno schema RESTful. Un altro esempio esclude i nomi della raccolta per le risorse secondarie quando può esistere solo una specifica risorsa figlio a livello n:

/folder/:id/:set_id/:cards_id

Mi scuso se ho causato più confusione. Il mio punto è che ci sono molte opzioni che sono considerate accettabili da diversi gruppi. Qualunque sia la convenzione, mantienila coerente e conserva una buona documentazione per chiunque abbia finito di utilizzare la tua API.