Progettare una buona API è un'arte. Una buona API è apprezzata anche dopo che il tempo passa. A mio avviso, non ci dovrebbe essere alcun pregiudizio generale sulla linea astratto-concreto. Alcuni parametri possono essere concreti come i giorni della settimana, alcuni richiedono di essere progettati per l'estensibilità (ed è piuttosto stupido renderli concreti, ad esempio parte dei nomi di funzioni), l'ennesimo può andare anche oltre e per avere un'elegante L'API one deve fornire callback o anche un linguaggio specifico del dominio aiuterà a combattere la complessità.
Ci sono raramente cose nuove che accadono sotto la Luna. Dai un'occhiata alla tecnica precedente, in particolare agli standard e ai formati stabiliti (ad esempio, molte cose possono essere modellate dopo i feed, le descrizioni degli eventi sono state elaborate in ical / vcal). Rendi la tua API facilmente additiva, dove le entità frequenti e onnipresenti sono concrete e le estensioni previste sono dizionari. Esistono anche alcuni modelli consolidati per affrontare situazioni specifiche. Ad esempio, la gestione della richiesta HTTP (e simili) può essere modellata nell'API con gli oggetti Request e Response.
Prima di progettare API, fai un brainstorming su aspetti, inclusi quelli, che non saranno inclusi, ma devi essere consapevole di ciò. Esempi di questo sono linguaggio, direzione della scrittura, codifica, locale, informazioni sul fuso orario e simili. Presta attenzione ai luoghi in cui possono apparire i multipli: usa la lista, non il singolo valore per loro. Ad esempio, se stai definendo l'API per il sistema di videochat, la tua API sarà molto più utile, se assumi N partecipanti, non solo due (anche se le tue specifiche al momento sono tali).
A volte, essere astratti aiuta a ridurre drasticamente la complessità: anche se si progetta una calcolatrice per aggiungere solo 3 + 4, 2 + 2 e 7 + 6, potrebbe essere molto più semplice implementare X + Y (con limiti tecnicamente fattibili su X e Y e includi ADD (X, Y) nella tua API invece di ADD_3_4 (), ADD_2_2 (), ...
Tutto sommato, scegliere in un modo o nell'altro è solo un dettaglio tecnico. La tua documentazione dovrebbe descrivere casi di utilizzo frequente in modo concreto.
Qualunque cosa tu faccia sul lato della struttura dati, fornisci un campo per una versione API.
Per riassumere, l'API dovrebbe ridurre al minimo la complessità quando si ha a che fare con il software. Per apprezzare l'API, il livello di complessità esposta dovrebbe essere adeguato. La decisione sulla forma dell'API dipende molto dalla stabilità del dominio del problema. Quindi, ci dovrebbe essere qualche stima su quale direzione il software e la sua API cresceranno, perché queste informazioni possono influenzare l'equazione per complessità. Inoltre, l'API desing è lì per le persone a capire. Se ci sono buone tradizioni nell'area della tecnologia del software in cui ti trovi, cerca di non deviare molto da loro, poiché ciò aiuterà a capire. Prendi in considerazione per chi scrivi. Gli utenti più esperti apprezzeranno la generalità e la flessibilità, mentre quelli con meno esperienza potrebbero essere più a loro agio con i concreti. Tuttavia, ci si prende cura della maggior parte degli utenti API lì, cioè quelli tra principianti ed esperti.
Per quanto riguarda la letteratura, potrei raccomandare "Beautiful Code", i principali programmatori spiegano come pensano Andy Oram, Greg Wilson, poiché penso che la bellezza riguardi la percezione dell'ottimalità nascosta (e dell'idoneità per qualche scopo).