Quando si crea un'API dovrei attenermi a piccole funzioni e molte chiamate o poche chiamate e grandi funzioni?

Che ne dici di fare entrambe le cose? Avere un'API " low level " (per così dire) che espone funzioni del sistema e ha un altro "livello" che espone servizi che un client potrebbe voler fare. Questo livello utilizza le necessarie API di basso livello richieste ma quelle sono ancora esposte se il cliente le desidera.

UPDATE: Per includere anche alcuni dei grandi punti e commenti fatti da altri.

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

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

Penso che lo stai guardando nel modo sbagliato. Non preoccuparti di grande | piccole chiamate o un sacco di | poche chiamate.

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

Hai:

• Utenti
• Criteri
• Prezzi
• ...

Quindi dovresti creare chiamate API intorno a quegli oggetti.

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

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

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

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

Per essere più prescrittivi, ciò creerà alcune chiamate che prendono un numero di parametri e potrebbero avere più chiamate sul back-end che sono oscurate dal client. Avrai anche alcune chiamate abbastanza veloci / semplici in cui l'API è poco più di un wrapper per la routine sottostante.

Penso che il tuo istinto sia giusto - rendere l'API semplice per i consumatori. In una certa misura, questa è la filosofia alla base di Contratti a tutela dei consumatori .

Più in particolare, l'API deve esporre casi di utilizzo aziendale idonei. 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 di per sé. Quale sarebbe un problema è se una grande funzione esegue sequenze di operazioni che potrebbero dover essere partizionate per consentire l'intervento del consumatore.

Personalmente, mi piacciono le API che:

1. sono ottimizzati in modo che i casi d'uso comune possano essere facilmente eseguiti
2. le chiamate relative alle operazioni CRUD sono orientate ai batch o hanno versioni batch
3. consente di reflection (così le persone che scrivono plugin o binding per altri linguaggi di computer possono automatizzare il processo)