API Spec Dulu, Baru Ngoding: Prinsip Lama yang Makin Relevan di Era AI

Bayangkan kamu sudah selesai mengerjakan UI yang rapi — layout bersih, logika form solid, validasi lengkap. Lalu kamu coba integrasikan dengan API backend, dan ternyata struktur response-nya berbeda dari yang kamu asumsikan sejak awal.

Field-nya beda nama. Nested object yang kamu harapkan ternyata flat. Ada field tambahan yang tidak kamu duga, dan ada yang kamu butuhkan ternyata tidak ada.

"Ini bukan cerita yang langka. Ini terjadi di hampir setiap project yang tidak punya satu elemen krusial: API Spec yang disepakati sebelum implementasi dimulai."

---

Masalahnya: Development Paralel Tanpa Alignment

Workflow development yang umum sering berjalan seperti ini:

• UI/UX design selesai
• Frontend mulai mengerjakan interface
• Backend secara paralel membangun endpoint
• Integrasi baru dicoba di penghujung project

"Frontend menunggu backend selesai; backend menunggu frontend mengkonfirmasi kebutuhan data — sementara deadline terus berjalan."

Ini bukan masalah kemampuan. Ini masalah koordinasi.

---

API Contract: Fondasi yang Sering Dilewatkan

API Spec (atau API Contract) adalah dokumentasi yang mendefinisikan bagaimana frontend dan backend berkomunikasi: endpoint yang tersedia, format request/response, header yang dibutuhkan, status code yang mungkin muncul, dan sebagainya.

Lima manfaat utama bagi frontend development:

1. Struktur data diketahui sejak awal

Tidak ada kejutan saat integrasi. Developer langsung tahu nama field, tipe data, dan struktur nested object yang akan diterima.

2. Model dan entity bisa didefinisikan lebih awal

Frontend bisa langsung membuat interface dan types yang mencerminkan struktur data API — memastikan konsistensi di seluruh layer aplikasi.

3. Development paralel yang sesungguhnya

Frontend bisa berjalan independen menggunakan mock data atau mock server yang sesuai dengan spesifikasi, tanpa harus menunggu backend selesai.

4. Integrasi yang lebih mulus

Ketika backend mengimplementasikan endpoint sesuai spesifikasi yang sama, integrasi menjadi proses "menghubungkan" — bukan menjembatani dua sistem yang berbeda asumsi.

5. Dokumentasi hidup

Spesifikasi memfasilitasi onboarding, debugging di masa depan, dan perubahan requirement — jauh lebih efektif dari membaca kode yang sudah ada.

---

Koneksi ke Clean Architecture

Robert C. Martin (Uncle Bob) merumuskan prinsip-prinsip relevan melalui Clean Architecture — pendekatan yang mengorganisir aplikasi ke dalam layer dengan tanggung jawab yang berbeda:

• Entities/Models (layer terdalam): Representasi data murni — dibuat langsung dari API Spec
• Use Cases/Interactors: Alur aplikasi dan logika bisnis
• Repository/Interface Adapters: Jembatan antara use cases dan sumber data
• Datasource/Frameworks (layer terluar): HTTP client konkret dan detail implementasi

"Layer terdalam tidak berubah ketika backend tersedia; hanya layer datasource terluar yang perlu dimodifikasi."

Ini berarti kamu bisa membangun dan menguji sebagian besar aplikasi sebelum backend selesai — selama kamu punya API Spec.

---

Relevansi di Era AI

Tanpa API Specification:

Developer meminta AI untuk "membuat user data repository." AI mengarang struktur data secara inkonsisten dan menghasilkan output yang perlu banyak revisi.

Dengan API Specification:

Spesifikasi yang detail memungkinkan AI menghasilkan kode yang presisi dan sesuai arsitektur secara langsung.

API Spec berfungsi sebagai grounding context — mencegah model AI menghasilkan struktur data yang fiktif. Dikombinasikan dengan layer Clean Architecture yang terpisah, developer bisa meminta AI menghasilkan seluruh architectural layer sekaligus dengan konteks yang tepat.

Agentic Workflows: Kemampuan AI yang semakin autonomous memungkinkan eksekusi sekuens — pembuatan entity, repository, use case, dan mock datasource — dalam satu sesi. Spesifikasi mencegah hallucination antar layer yang dihasilkan.

Spesifikasi sebagai Collective Prompt Engineering: API Spec adalah bentuk prompt engineering untuk seluruh tim — instruksi yang jelas untuk kolega, tools AI, dan diri kamu di masa depan.

---

Soal Deadline

Argumen yang sering muncul: "Kita tidak punya waktu untuk membuat API Spec; klien minta cepat."

Coba hitung berapa jam yang sudah dihabiskan untuk refactoring karena struktur data tidak cocok, atau debugging karena asumsi yang berbeda antara tim.

"Membuat API Spec bukan membuang waktu. Ini investasi beberapa jam yang menghemat puluhan jam setelahnya."

---

Kesimpulan

API Spec telah berevolusi dari dokumentasi opsional menjadi infrastruktur esensial — terutama relevan dalam konteks AI-assisted development, di mana spesifikasi yang presisi memungkinkan tim dan AI agents untuk menghasilkan implementasi yang konsisten dan sesuai arsitektur.

Mulai project berikutmu dengan API Spec. Bukan karena itu "best practice" — tapi karena itu yang membuat pekerjaan lebih mudah untuk semua orang yang terlibat.