Desain API memengaruhi cara tim membangun, mendokumentasikan, dan memakai sebuah sistem software. Dua pendekatan yang umum adalah design first dan code first. Dengan design first, tim menyepakati kontraknya sebelum implementasi. Dengan code first, implementasinya yang mendefinisikan kontrak.
Design first: arsitektur sebelum implementasi
Design first menaruh spesifikasi API di depan implementasi. Tim menjabarkan endpoint, payload, dan aturan-aturannya sebelum menulis kode service. OpenAPI atau Swagger bisa menyediakan format bersama untuk deskripsi itu.
Urutan ini ngasih tim spesifikasi yang terstruktur, dokumentasi yang ada sebelum kodenya, dan kesempatan untuk memvalidasi desainnya sebelum development dimulai. Cara ini bisa bikin komunikasi lebih jelas, menjaga API tetap konsisten, dan ngasih banyak tim sebuah kontrak untuk di-review. Biayanya adalah proses yang lebih lambat di awal dan kebutuhan akan orang yang bisa mengambil keputusan desain itu.
Code first: kecepatan lewat implementasi
Dengan code first, API-nya terbentuk seiring tim menulis implementasinya. Tim bisa langsung mulai ngoding, menyesuaikan behavior seiring requirement berubah, dan fokus ke fungsionalitas yang jalan.
Pendekatan itu bisa memperpendek siklus development pertama dan cocok untuk tim kecil, prototype cepat, atau proyek yang requirement-nya masih belum jelas. Tanpa langkah desain yang terpisah, endpoint bisa jadi nggak konsisten. Dokumentasinya juga bisa ketinggalan dari kodenya, yang bikin perubahan API berikutnya lebih susah dikoordinasikan.
Memilih di antara kedua pendekatan
Design first cocok untuk proyek enterprise, sistem yang kompleks, tim yang lebih besar, dan situasi di mana dokumentasi yang detail jadi bagian dari deliverable. Code first cocok untuk prototype cepat, scope yang terbatas, tim kecil yang komunikasinya dekat, atau requirement yang berubah dengan cepat.
Pilihannya harus mengikuti kompleksitas proyek, struktur tim, kebutuhan bisnis, dan seberapa jelas requirement-nya dipahami. Sebuah tim juga bisa menggabungkan kedua pendekatan. Tim bisa menyepakati kontrak utamanya dulu dan memakai kerja implementasi untuk menyelesaikan detail yang tersisa.
Nggak ada satu metode yang cocok untuk setiap proyek. Mulai dari seberapa banyak koordinasi yang dibutuhkan proyeknya. Kalau beberapa client bergantung pada kontrak yang sama, menulis dan me-review desain API sebelum implementasi biasanya mencegah lebih banyak rework. Kalau masalahnya masih dieksplorasi, potongan kecil code first bisa memunculkan requirement yang belum ketahuan dengan cepat.
Yang saya lihat dalam praktik
Dari pengalaman profesional saya mengembangkan API selama beberapa tahun, kebanyakan proyek kompleks yang saya kerjakan pakai design first. Seiring sistem teknologinya tumbuh, konsistensi dan dokumentasi jadi makin susah dipulihkan belakangan.
Di startup financial technology tempat saya kerja sekarang, tim saya pakai design first karena kami men-support aplikasi mobile. Desain API yang konsisten penting buat kedua sisi, dan dokumentasi API kami berperan sebagai source of truth. Kami memperlakukan dokumen itu sebagai kontrak yang harus diikuti oleh mobile client dan service-nya.
Tim saya sebelumnya pakai code first, padahal tim itu juga punya aplikasi mobile. Kontraknya tinggal di kode dan di obrolan langsung antar tim, bukan di dokumen API. Development-nya terasa cepat dan fleksibel, tapi kami sering kena masalah konsistensi. Keputusan yang diambil selama implementasi gampang terlupakan, jadi pada akhirnya kami tetap butuh dokumentasi API sebagai referensi.
Tradeoff-nya
Saran saya, jangan kunci sebuah proyek ke satu metodologi. Teknologi dan requirement berubah, jadi proses desain API juga harus ikut berubah. Tinjau ulang pilihannya waktu timnya bertambah besar, ada client baru, atau biaya dari keputusan yang nggak terdokumentasi mulai kelihatan.
Sebuah API butuh kontrak yang jelas dan implementasi yang benar. Pilih pendekatan yang ngasih orang-orang yang memakai API itu cukup kepercayaan diri untuk membangun di atasnya.
Memuat komentar...