Quando creo un API dovrei rimanere con piccole funzioni e molte chiamate, o poche chiamate e grandi funzioni?

Ho una piattaforma di binari che mantengo. Ha molte applicazioni web diverse costruite su di esso. Tuttavia ora un client richiede un'API in modo che possano mantenere gli utenti sul loro sito, ma trarre vantaggio da alcune delle attività automatizzate che abbiamo.

La piattaforma viene utilizzata per creare applicazioni assicurative e consente il loro acquisto online, oltre a fornire modi per scaricare la documentazione relativa alla polizza.

Quindi la mia domanda quando si crea l'API è questa:

Quando devo fare un sacco di cose, come validate, creare una user, user profilee policy, più o meno allo stesso tempo. Devo effettuare 4 chiamate API separate e fare in modo che il client crei 4 chiamate dalla loro parte. O dovrei avere una chiamata che esclude molti parametri, che convalida il client e crea tutte e 3 queste cose contemporaneamente, semplificando le cose per il cliente?

Il client, in questo caso, ottiene tutte le informazioni richieste contemporaneamente, quindi non è come se ci fosse un flusso naturale nella loro applicazione in cui si ferma e possono effettuare una chiamata API alla mia piattaforma.

Essendo stato sul lato client usando molte API prima, il mio istinto è quello di renderlo il più semplice possibile per il client e fargli fare una sola chiamata. Tuttavia, ciò sta portando a un livello piuttosto ampio functionsnell'API, di cui non sono un fan.

Come mi consigli di affrontare questo?

Come nota, non sono molto fiducioso nella capacità dei clienti di implementare un'API complicata dalla loro parte.

Che ne dici di fare entrambi? Avere un'API "di basso livello " (per così dire) che espone le funzioni del sistema e abbia un altro "livello" che espone i servizi che un client potrebbe voler fare. Questo livello userebbe le necessarie API di basso livello richieste ma quelle sono comunque esposte se il client le desidera.

AGGIORNAMENTO: Includere anche alcuni dei grandi punti e commenti fatti da altri.

1. Considera se il client dovrà mai chiamare uno dei metodi API più piccoli, ad es. È possibile chiamare createUserProfile senza chiamare anche createUser? In caso contrario, non esporre quel metodo. Grazie NoobsArePeople2

2. Un punto semplice ma eccellente. Punto chiave con l'esposizione di qualcosa in un'API: non puoi mai smascherarla. Esporre il minimo necessario per funzionare e quindi espandersi piuttosto che esporre tutto e ... beh, allora è nudo e apportare modifiche può essere imbarazzante e imbarazzante . Grazie MichaelT

Penso che tu lo stia guardando nel modo sbagliato. Non preoccuparti per le grandi | piccole chiamate o molte | poche chiamate.

Pensa agli oggetti business e alle azioni che possono essere eseguite con | per | contro quegli oggetti.

Hai:

• utenti
• Politiche
• Aliquote
• ...

Quindi dovresti creare chiamate API attorno a quegli oggetti.

• User.Create
• User.UpdatePassword
• Policy.Validate
• ...

L'idea è quella di creare operazioni atomiche o quasi atomiche basate sugli oggetti business e sulle loro azioni. Ciò semplificherà la progettazione e la codifica: chiamate che fanno ciò che l'oggetto aziendale dovrebbe fare e che corrispondono al modello mentale o alle aspettative dei programmatori. Quando i programmatori o gli architetti stanno discutendo i requisiti con gli analisti aziendali, tutti possono usare la stessa terminologia e lo stesso flusso generale di operazioni.

Il problema con chiamate di tipo più grande e all-in-one è il rischio di effetti collaterali. Se Policy.Create genera anche un utente e innesca qualche altra azione, ciò spezzerebbe le aspettative dei programmatori. Allo stesso modo, molte piccole chiamate costringono il programmatore a ricordare di chiamare A e poi B e poi C per eseguire una "singola" operazione commerciale.

E il modo in cui nominerai le chiamate si baserà su ciò che Rails e i tuoi servizi web di supporto supporteranno.

Per essere più prescrittivi, questo creerà alcune chiamate che accettano un numero di parametri e potrebbero avere più chiamate sul back-end che sono oscurate al client. Finirai anche con alcune chiamate abbastanza rapide / semplici in cui l'API è poco più di un wrapper per la routine sottostante.

Penso che il tuo istinto sia giusto: rendi l'API semplice per i consumatori. In una certa misura, questa è la filosofia alla base dei contratti guidati dai consumatori .

Più specificamente, l'API dovrebbe esporre casi di utilizzo aziendale adeguati. Considera il dominio aziendale a portata di mano: c'è davvero bisogno di quelle funzioni di basso livello? Qual è lo svantaggio di incapsularli? Le grandi funzioni nell'API non sono un problema in sé e per sé. Quale sarebbe un problema è se una grande funzione mette in sequenza le operazioni che potrebbero dover essere partizionate per consentire l'intervento del consumatore.

Personalmente, mi piacciono le API che:

1. sono ottimizzati in modo da poter eseguire facilmente casi d'uso comuni
2. le chiamate relative alle operazioni CRUD sono orientate al batch o hanno versioni batch
3. consente la riflessione (così le persone che scrivono plugin o associazioni per altri linguaggi informatici possono automatizzare il processo)