Ci sono più dimensioni di design. Essere pedante (e ottimizzato):
-
Consistente : operazioni simili appaiono simili tra le interfacce
-
Utilizzabile : l'API risolve la maggior parte dei problemi degli utenti con un piccolo file di testo aggiunto
-
Semplice : le operazioni esprimono un singolo intent (probabilmente possono essere riassemblate in modo utile dal client)
-
Incapsulato : l'API espone un'interfaccia minima (massimizzando quale implementazione può cambiare senza rompere i chiamanti)
La scelta del design dovrebbe dipendere dal modo in cui la tua API interagisce con il resto del sistema, "livello" (basso / alto) della tua API, quanto è ben definito il problema, ecc.
Se stai progettando qualcosa che assomiglia molto alle API esistenti, in particolare le API di sistema, la coerenza è probabilmente più importante dell'usabilità. Come altri hanno già detto, l'usabilità potrebbe essere sovrapposta come API separata. Probabilmente l'API di livello superiore dovrebbe essere progettata per l'usabilità.
Le API di basso livello dovrebbero concentrarsi sulla semplicità poiché potrebbero essere potenzialmente utilizzate da molte API di livello superiore. Essere in grado di combinare le chiamate in modi diversi è importante.
L'incapsulamento è particolarmente importante se il problema non è ben esplorato. L'esposizione di un sacco di un'interfaccia sperimentale richiede di avere un sacco di codice client danneggiato (o di dover mantenere il codice legacy) se si deve modificare il progetto. In questo caso, può avere senso ignorare la semplicità / consistenza e invece esporre solo il minor numero possibile di funzioni.