Il modo migliore nell'API REST per richiedere una rappresentazione di riepilogo di una risorsa?

Question

Ho una API REST che si occupa di una grande risorsa, i clienti. Il cliente a volte desidera una rappresentazione abbreviata/sommaria di un cliente. Quale sarebbe un buon modo per specificare che la richiesta è per una rappresentazione sommaria?

Per ottenere una rappresentazione completa per il cliente 123 la sua: /customers/123

Per ottenere una rappresentazione di sintesi è /customers/123/summary un buon modo? Ci sono opzioni migliori?

Answer 1

Per rendere la soluzione riutilizzabile e flessibile, suggerirei di implementare un parametro di query "filtro". Lì, si può mettere tutti i campi richiesti dal cliente:

GET /customers/123?fields=id,first_name,last_name,email 

In questo modo se in seguito è necessario creare una sintesi diversa per un compito diverso, non avrete nulla da modificare.

Non consiglierei /customers/123/summary perché non è flessibile. Potrebbe essere ok per un caso, ma se il cliente ha bisogno di accedere a diverse proprietà per un caso diverso, sarà necessario modificare la risorsa (molto probabilmente restituendo più campi del necessario). Se si vuole "nascondere" i nomi dei campi, forse in alternativa potrebbe essere qualcosa di simile:

GET /customers/123?view=DESCRIPTION 

Dove "DESCRIPTION" sarebbe descrivere il tipo di sintesi. Ad esempio:

GET /customers/123?view=addresses_only // eg. returns billing and home address 
GET /customers/123?view=short // eg. returns only id, first name, last name 

Questo è ancora flessibile poiché è possibile creare facilmente nuove viste.