Merancang API yang baik adalah seni. API yang baik dihargai bahkan setelah waktu berlalu. Menurut pendapat saya, seharusnya tidak ada bias umum pada garis abstrak-konkret. Beberapa parameter bisa sekonkret hari dalam seminggu, beberapa perlu dirancang untuk diperpanjang (dan itu cukup bodoh untuk membuatnya konkret, misalnya, bagian dari nama fungsi), namun yang lain mungkin lebih jauh dan untuk memiliki keanggunan API yang satu perlu menyediakan panggilan balik atau bahkan bahasa khusus domain akan membantu memerangi kompleksitas.
Jarang terjadi hal-hal baru di bawah Bulan. Lihatlah seni sebelumnya, terutama standar dan format yang ditetapkan (misalnya, banyak hal dapat dimodelkan setelah feed, deskripsi acara diuraikan dalam ical / vcal). Jadikan API Anda mudah tambahan, di mana entitas yang sering dan berada di mana-mana konkret dan ekstensi yang dibayangkan adalah kamus. Ada juga beberapa pola mapan untuk menghadapi situasi tertentu. Misalnya, menangani permintaan HTTP (dan yang serupa) dapat dimodelkan dalam API dengan objek Permintaan dan Respons.
Sebelum merancang API, bertukar pikiran tentang berbagai aspek, termasuk yang tidak akan disertakan, tetapi Anda harus sadar. Contohnya adalah bahasa, arah penulisan, pengodean, lokal, informasi zona waktu dan sejenisnya. Perhatikan tempat-tempat di mana kelipatan dapat muncul: gunakan daftar, bukan nilai tunggal untuk mereka. Misalnya, jika Anda menginginkan API untuk sistem videochat, API Anda akan jauh lebih bermanfaat, jika Anda mengasumsikan N peserta, bukan hanya dua (walaupun spesifikasi Anda saat ini demikian).
Kadang-kadang, menjadi abstrak membantu mengurangi kompleksitas secara drastis: bahkan jika Anda merancang kalkulator untuk menambahkan hanya 3 + 4, 2 + 2, dan 7 + 6, mungkin jauh lebih mudah untuk mengimplementasikan X + Y (dengan batasan yang secara teknis layak pada X dan Y, dan sertakan ADD (X, Y) ke API Anda alih-alih ADD_3_4 (), ADD_2_2 (), ...
Singkatnya, memilih satu cara atau lain hanyalah detail teknis. Dokumentasi Anda harus menggambarkan kasus penggunaan yang sering terjadi secara konkret.
Apa pun yang Anda lakukan di sisi struktur data, berikan bidang untuk versi API.
Untuk meringkas, API harus meminimalkan kompleksitas ketika berhadapan dengan perangkat lunak Anda. Untuk menghargai API, tingkat kompleksitas yang terekspos harus memadai. Memutuskan bentuk API sangat bergantung pada stabilitas domain masalah. Dengan demikian, harus ada beberapa estimasi pada arah mana perangkat lunak dan API itu akan tumbuh, karena informasi ini dapat mempengaruhi persamaan untuk kompleksitas. Juga, desing API ada untuk dipahami orang. Jika ada tradisi bagus di bidang teknologi perangkat lunak tempat Anda berada, cobalah untuk tidak menyimpang banyak darinya, karena itu akan membantu pemahaman. Mempertimbangkan untuk siapa Anda menulis. Pengguna yang lebih maju akan menghargai sifat umum dan fleksibilitas, sementara mereka yang kurang berpengalaman mungkin lebih nyaman dengan konkret. Namun, perhatikan sebagian besar pengguna API di sana,
Di sisi literatur saya dapat merekomendasikan "Kode Indah" Programmer Terkemuka Jelaskan Bagaimana Mereka Berpikir Oleh Andy Oram, Greg Wilson, karena saya pikir kecantikan adalah tentang merasakan optimalitas tersembunyi (dan kesesuaian untuk beberapa tujuan).