Qual è la migliore struttura di URL RESTful per una risorsa ricorsiva?

Sto creando un servizio RESTfull per una struttura di risorse ad albero e mi chiedevo quale sarebbe la migliore struttura URL?

Ho tre requisiti:

essere in grado di ottenere una raccolta di risorse di root
essere in grado di ottenere una singola risorsa
essere in grado di ottenere una raccolta di risorse secondarie

Il mio pensiero attuale è:

/rest/documents
/rest/documents/{id}
/rest/documents/{id}/documents

Stavo anche pensando di seguire i percorsi singolari / plurali per indicare elenchi o singoli elementi, ma so che avrò una risorsa che è lo stesso plurale in quanto singolare, quindi ho deciso di non farlo.

Qualcuno ha qualche idea su quanto sopra? o hai un modo diverso / migliore di strutturarlo?

web-services

— Matt Brailsford
fonte

Potrei essere frainteso la domanda, ma mentre stiamo parlando di URL è SEO un problema?

— Jon Hopkins,

La SEO non è un problema, no. Fondamentalmente sto chiedendo la migliore struttura di URL logici per una risorsa autoreferenziale.

— Matt Brailsford,

Mi sembra piuttosto semplice.

— Tim Post

Quanto può essere profonda questa struttura?

— Martijn Verburg,

@Martijn la profondità è illimitata

— Matt Brailsford il

Risposte:

Quello che mi viene in mente è: non lasciare che l'API RESTful rifletta la ricorsività nell'URL stesso. Vieni a pensarci bene, la tua risorsa è solo i documenti.

Se i tuoi documenti sono archiviati fisicamente in base alla struttura ricorsiva, crea una mappatura su un ID univoco e utilizza l'ID nell'URL:

/rest/documents/{id}

Ora, se hai i tuoi documenti in questo modo:

| DocumentName | DocumentPath | DocumentID |
--------------------------------------------
| abc | / abc | 1 |
| asd | / abc / asd | 2 |
| asd | / asd | 3 |
| ciao | / abc / asd / boo | 4 |
| ehi | / abc / asd / hey | 5 |

la richiesta dovrebbe consultare questo URL per il /abc/asddocumento

GET /rest/documents/2

Quindi, ora devi fornire agli utenti della tua API i mezzi per attraversare la tua struttura con poco sforzo. Ciò potrebbe essere fatto avvolgendo il payload di risposta (documento) in un oggetto, contenente ulteriori informazioni di movimento, come questo:

{
   data: { /* your document goes here */ },
   parent: {"abc": 1 },
   children: [ { "boo": 4 }, { "hey": 5} ]
}

purché si preveda che gli utenti non creino troppi documenti in un unico livello, è possibile includere un elenco di elementi secondari nella risposta. In caso contrario, potresti offrire all'utente di recuperare gli ID documento figlio in questo modo, consentendo ad esempio di effettuare il paging dei risultati tramite i parametri di querystring:

GET /rest/documents/2/children?page=2&size=50

Infine, parlando di parametri di querystring, potresti anche fornire le informazioni sul percorso direttamente attraverso i parametri di querystring:

GET /rest/documents?path=somepath&page=1&size=42

Tutti gli approcci citati prevedono che la pianura GET /rest/documentsrestituisca solo documenti radice.

— netchkin
fonte

Buona idea. Tuttavia, la relazione con i documenti figlio non è chiara dall'API se i documenti figlio sono inclusi nella risposta per un documento. Se i documenti hanno anche un'altra risorsa secondaria, ad esempio commenti, in genere si accede alle domande per un documento utilizzando / documents / {id} / questions. Per essere coerente e chiarire la relazione con i documenti secondari nell'API, suggerirei di accedere ai documenti secondari tramite / documenti / {id} / documenti secondari. Le rappresentazioni restituite sarebbero Documenti proprio come / documenti / {id}. Quindi, anche il resto di ciò che hai descritto qui funziona ancora.

— Nathan Ward,

Qualcosa del genere forse:

/rest/{rootEntity}/Item/{leafEntity}/{id}
/rest/{entity}/ItemList
/rest/{entity}/ItemList/{leafEntity}

dove {rootEntity} è il punto di partenza della tua raccolta, {leafEntity} è un nodo foglia con nome all'interno dell'albero.

È possibile aggiungere alcuni dei parametri sopra elencati per selezionare, ad esempio, Ultimi o Tutti o qualcosa del genere.

— Gary Rowe
fonte