Enam Baris YAML yang Mengubah Kontrak API
Respons 404 yang tidak ada di OpenAPI itu bug kontrak, bukan kelalaian dokumentasi. Enam baris YAML langsung mengubah tipe TypeScript konsumen.
Ringkasan
Awalnya kirain cuma nambah dokumentasi karena ubah YAML enam baris dan generate tipe TS, nggak ngaruh runtime. Padahal openapi-typescript nurut banget sama YAML jadi kalau 404 nggak ditulis tipenya jadi unknown dan frontend harus nebak manual. Begitu skema 404 ditambahin, tipe error langsung kebaca di compiler jadi kontrak API lebih solid dan nggak gampang jebol di produksi.
Saya lagi ngecek diff commit kecil di repo portal kota tempat saya kerja. Layar terminal cuma menampilkan dua file yang berubah. File pertama, api/docs/openapi.yaml, bertambah enam baris. File kedua, frontend/src/lib/api/v1.d.ts, bertambah sembilan baris sebagai hasil regenerasi otomatis. Tidak ada perubahan logika bisnis atau runtime sama sekali.
Awalnya saya berpikir ini cuma urusan administratif. Nambah dokumentasi doang, pikir saya. Toh endpoint untuk mengambil data ulasan wisata sudah berjalan stabil. Server tetap mengembalikan status yang sama, dan frontend tetap bisa menampilkan data. Saya mengira commit sekecil ini aman saja dan nggak akan berdampak pada alur kerja tim.
Ternyata dugaan saya meleset.
Tebakan yang Meleset
Masalahnya muncul saat saya melihat bagaimana openapi-typescript bekerja. Tools ini mengubah skema OpenAPI 3.0 atau 3.1 menjadi tipe TypeScript murni tanpa runtime [8]. Artinya, dia sangat patuh pada apa yang tertulis di file YAML.
Biasanya, tanpa dokumentasi yang jelas, frontend developer akan melakukan pendekatan trial and error. Mereka menjalankan aplikasi, memicu kondisi error, lalu membuka Network tab di browser untuk mengintip respons mentah dari server. Setelah itu, mereka membuat interface TypeScript secara manual berdasarkan apa yang mereka lihat di layar.
Masalahnya, pendekatan ini rapuh. Kalo suatu hari backend memutuskan untuk mengubah nama field dari message menjadi error_message, frontend tidak akan mendapat peringatan dari compiler. Error baru akan muncul di produksi, dan itu adalah mimpi buruk yang sebenarnya bisa dihindari.
Enam Baris yang Mengubah Kontrak
Ketika skema respons 404 NOT_FOUND ditambahkan ke dalam YAML, tipe error tersebut langsung muncul di hasil generate. Konsumen API sekarang bisa mengakses detail error lewat paths[...][get][responses][404] di file v1.d.ts [8].
Sebagai contoh, sebelum perubahan, tipe data untuk endpoint tersebut mungkin hanya mendefinisikan respons 200 OK. Saat server mengembalikan 404, TypeScript menganggapnya sebagai unknown atau memaksa developer menggunakan any. Setelah perubahan, tipe data tersebut secara otomatis mencakup properti seperti code dan message dengan tipe string yang spesifik.
Sebelum enam baris itu ada, tipe error tersebut tidak eksis di mata TypeScript. Frontend developer dipaksa menebak-nebak bentuk objek error saat resource tidak ditemukan. Mereka harus membuka kode server atau mencoba memicu error secara manual cuma buat tahu struktur JSON yang dikembalikan. Ini bukan sekadar ketidaknyamanan, ini adalah kebocoran abstraksi yang memperlambat development.
Prosesnya sendiri sebenarnya sangat sederhana. Saya cukup menjalankan perintah generate di terminal. Dalam hitungan detik, v1.d.ts diperbarui. Tidak ada logika bisnis yang tersentuh, tidak ada risiko regresi pada runtime. Yang berubah hanyalah jaminan tipe data yang diberikan oleh compiler kepada developer.
Bukan Sekadar Dokumentasi
Di sinilah pola pikir saya berubah total. Respons error yang tidak ada di spesifikasi OpenAPI itu adalah bug kontrak, bukan kelalaian dokumentasi biasa.
Generated types hanya mengakui apa yang tertulis secara eksplisit. Dengan menambahkan enam baris YAML dan melakukan regenerasi, konsumen API jadi tahu persis bentuk respons 404 tanpa perlu membaca satu baris pun kode server. Kontrak antara backend dan frontend menjadi utuh dan dapat diandalkan oleh compiler.
Mengapa ini masuk akal? Karena API adalah perjanjian. Kalo kita hanya mendokumentasikan skenario sukses, kita secara tidak langsung memberitahu konsumen bahwa error tidak akan pernah terjadi. Padahal, jaringan bisa putus, data bisa terhapus, dan ID bisa salah. Mengakomodasi realitas ini dalam kontrak adalah tanda profesionalisme.
Saya pribadi lebih memilih pendekatan eksplisit seperti ini. Memang butuh usaha ekstra untuk mendefinisikan setiap kemungkinan error, tapi hasilnya sepadan. Tim frontend nggak perlu lagi menerka-nerka atau membuat interface any darurat yang rentan error. Semua aturan main sudah tertulis jelas di satu sumber kebenaran.
Banyak developer lupa bahwa respons 404 wajib didokumentasi sebagai bagian integral dari kontrak API, bukan sekadar catatan kaki. Kalo sedang membangun API, pastikan setiap skenario error memiliki definisi yang jelas. Intinya, setiap respons 404 wajib didokumentasi agar tipe TypeScript bisa benar-benar diandalkan oleh seluruh tim. Jangan biarkan konsumen API bekerja dalam kegelapan hanya karena kita malas menulis enam baris tambahan.