Prendi ad esempio le seguenti due richieste di GET con argomenti leggermente diversi:
../user/login_at
che restituisce l'ultima data di accesso dell'utente e
../user/login_at?start=2015-05-01&end=2015-05-31
che restituisce una matrice di tutte le date di accesso dell'utente entro maggio.
Esistono aspetti negativi di questa API per eseguire queste due funzioni leggermente diverse?
Potrei pensare, nel primo esempio l'utente si aspetta una stringa o un valore dell'oggetto json da restituire. Ma nel secondo esempio, l'utente si aspetta di restituire un array. Può indurre l'utente a creare un'istruzione% ca_de% disordinata.
Sarebbe meglio se si rinomina l'endpoint in.
if else
e
/user/last_login_at
No. Penso che siano chiari e dovrebbero essere diversi perché svolgono compiti diversi, anche se svolgono attività per la stessa entità.
Forse crei un parametro booleano, in modo da recuperare l'ultimo accesso:
/ user / login_at? Ultima
In questo modo hai effettivamente un endpoint che filtra per stringa di query e potresti usare una chiamata come:
/ user / login_at start = 2015/05/01 &? = Fine 2015/05/31 & ultima
... per ottenere l'ultimo tempo di accesso a maggio.
Potrebbe esserci qualche inconveniente nell'analisi della risposta, come già notato da bekicot in questa risposta :
Il problema è che il tuo risultato ha una struttura diversa per i due casi.
Perché ha questa differenza gratuita?
Basta fare la prima risposta alla query con un array a elemento singolo, e tutto va bene.
A parte questo, non c'è alcun problema. È analogo al sovraccarico di funzioni in linguaggi come il C ++, dove sovraccarichi diversi (numero e tipo di parametri diversi) possono restituire diversi tipi di risultato.
Mi sta bene. Se conosci utenti potenziali dell'API, potresti chiedere loro se sarebbe meglio restituire sempre un array; con una voce se è richiesto solo l'ultimo accesso dell'utente; questo significa anche che restituire un array vuoto è un modo perfetto per dire al client che l'utente non ha mai effettuato l'accesso.
Il client può quindi utilizzare un codice identico per elaborare la risposta al punto in cui ha una matrice di oggetti, in genere 1 e talvolta 0 voci nel primo caso e un numero qualsiasi di voci nel secondo caso.
Leggi altre domande sui tag api-design