E 'una cattiva pratica restituire diversi tipi di dati da endpoint API Web alternativi?

3

Considera un'API Web con un endpoint api\LargeItem

Un LargeItem è un oggetto piuttosto grande con molte proprietà e stringhe lunghe.

Un utente può GET uno come così api\LargeItem che restituisce LargeItem con Id 1

Tuttavia abbiamo spesso bisogno di compilare elenchi di questi elementi per la selezione degli utenti e, quando lo facciamo, non abbiamo mai bisogno del grande oggetto idratato ricco.

Da un lato l'utente può aspettarsi di chiamare solo api\LargeItem e di recuperarli tutti ... ma non intendo mai che il mio utente consumi la grande collezione di oggetti ricchi come questo. Quando vogliono una lista preferisco dare loro SmallerVersionOfLargeItem che forse ha solo Id e Nome, per esempio.

Esiste una linea guida o uno standard per stabilire se è possibile restituire oggetti di forma diversa dall'endpoint omonimo con inclusioni URL diverse?

È preferibile avere un endpoint come api\SmallerVersionOfLargeItems\ ?

EDIT equivale al concetto ShouldSerialize in JSON.Net eccetto senza utilizzare una proprietà ?fields nella chiamata API.

Per chiarire: My Api api non usa i termini "Large" e "Small" nella realtà. Li sto solo usando qui per illustrare che questi sono solo diversi set di campi dello stesso oggetto.

    
posta Matthew 15.06.2015 - 19:11
fonte

1 risposta

4

Questo endpoint:

api\Items

Non è uguale a questo:

api\Items

Pertanto, possono restituire risposte diverse. Come hai indicato, ottenere gli oggetti può solo restituire una lista con solo poche proprietà mentre ottenere un oggetto tramite ID può restituire un oggetto più pesante. Evitare termini decifrabili come "piccolo" e "grande" nell'API / endpoint se gli endpoint sono denominati in quel modo.

Inoltre, sarebbe consigliabile anche mettere una versione sull'endpoint. In conclusione, più semplice è l'API, più facile sarà per altri utenti.

    
risposta data 15.06.2015 - 19:44
fonte

Leggi altre domande sui tag