API nidificate - Discussione sulle buone pratiche

Troverai risposte opinate su questo perché è soggettivo al caso d'uso. Non c'è una risposta giusta qui. Idealmente, si progetta l'API per adattarla al meglio al proprio caso d'uso.

1. event/:event-id/members vs /members Domande che mi chiedo: la risorsa "membro" sarà isolata? Ad esempio:

   • Avrò bisogno di recuperare membri attraverso eventi (per esempio eseguendo analisi)? Posso sempre ottenere /members e filtrare su event-id come parametro di query.

   • Voglio aggiungere più endpoint per supportare un utilizzo più pulito, come il POST event/:id/members e GET /members/:id ?

2. Ho scoperto che l'annidamento nel modo in cui si menziona (3 livelli) non si adatta bene per lo stesso motivo sopra - oggi si annidano i membri sotto mini evento. Domani, se hai bisogno di accedere ai membri attraverso gli eventi (analisi come un esempio), dovrai duplicare un endpoint. Se si trattava di un livello di root, di nuovo, è sufficiente aggiungere parametri.

Nel tuo caso, se un membro può appartenere a un evento e a un mini evento, hai già più endpoint. Evitalo, rende la documentazione più difficile.

Evita qualcosa come PATCH event/:event-id/mini-event/:mini-event-id/members/:member-id . PATCH members/:id è più facile da lavorare con

In conclusione, ecco cosa puoi fare. Usa GET per /members/ e /mini-events/ con parametri di query. POST, PUT, PATCH e DELETE per /events/:event-id/members/:member-id e /events/: event-id/mini-events/:mini-event-id .

Alcuni link rilevanti link

L'endpoint REST non ha necessariamente nulla a che fare con lo schema del database. Almeno non dovrebbe dipendere su di esso, dopotutto potrebbe aggregare dati che non sono correlati direttamente nel database.

Considerando il tuo esempio, mi aspetterei che GET /event/:eventid/members recuperi tutti i membri di un evento e pertanto l'aggiunta di membri utilizzerà lo stesso endpoint. È sicuramente molto più RESTful che chiamare /members e passare l'id dell'evento come parametro. Sarebbe uno stile di pagina web basato su moduli per fare cose.

Per quanto riguarda il tuo secondo esempio, dipende. Potresti persino creare eventi regolari in mini-eventi, che hanno solo una relazione genitore-figlio. Quindi ti sbarazzi di un livello di nidificazione e non hai bisogno di verificare che :mini-event-id sia in effetti parte di :event-id . Per esempio. /event/:eventid/mini-events/ elencerebbe tutti i mini-eventi relativi a un evento, ma sarebbero comunque accessibili attraverso /event/:mini-event-id .

Ci sono alcuni problemi reali con i parametri url in generale quando inizi a inviarne di più

• Come analizzare il nostro endpoint se hai / events /: eventId e / events / anotherEndPoint / o / events /: customerId

• La lunghezza dell'URL è in pratica limitata. / events /: guid / childObject /: guid / childObject /: guid ... etc non andare avanti per sempre

• Gli alberi oggetto potrebbero non corrispondere ai parametri della query. cioè voglio miniEventId: 123 ma non so a quale evento appartenga.

È è RESTfull per imitare una struttura ad albero in stile directory con i tuoi endpoint, ma è più importante avere un'API efficiente e facile da usare.

Il brutto:

/events/:eventId?withMiniEvents=true

Potrebbe significare 500ms dal tuo tempo per l'interazione. Preferiresti essere RESTFull? stai facendo HATEOAS?