Changelog API: apa yang dipublikasikan, siapa pembacanya

Changelog API adalah catatan bertanggal dari setiap perubahan yang mungkin diperhatikan oleh pemanggil, ditulis untuk orang yang mengintegrasikan API tersebut, bukan untuk tim yang merilisnya. Audiens ini membuatnya menjadi dokumen yang berbeda dari changelog produk: pembaca sedang memutuskan apakah kodenya masih akan berfungsi bulan depan. Kebanyakan gagal dengan cara yang sama, menjadi salinan tersaring dari feed rilis internal, sehingga sebuah field yang dihapus berada di sebelah perbaikan teks dengan bobot yang sama, dan keduanya tidak dibaca.

Apa itu changelog API?

Ini adalah log publik dan bertanggal tentang perubahan pada antarmuka yang telah ditulis kodenya oleh orang lain. Tes yang berguna untuk menentukan apakah sesuatu pantas masuk di dalamnya tidak ada hubungannya dengan seberapa besar perubahan itu secara internal. Ia bertanya apakah pemanggil yang benar, ditulis tahun lalu dan tidak pernah disentuh sejak itu, bisa berperilaku berbeda karena itu. Tes ini menerima beberapa perubahan yang sangat kecil dan mengecualikan beberapa yang sangat besar.

Semua di bawah ini mengasumsikan pemanggil berada di luar perusahaan dan pada dasarnya tidak terjangkau kecuali lewat dokumen ini. Saat pemanggilnya adalah tim lain di perusahaan yang sama, perhitungannya berubah cukup banyak sehingga butuh perlakuan sendiri; changelog API internal membahas apa yang dibutuhkan audiens itu sebagai gantinya.

Cara menulis panduan migrasi API membahas dokumen terakhir itu secara lengkap; singkatnya, itulah yang seharusnya ditautkan entri perubahan tak kompatibel alih-alih mencoba menggantikannya.

Kelimanya adalah dokumen terpisah dengan siklus hidup terpisah. Pemberitahuan deprecation adalah janji dengan tanggal, dan juga masuk ke changelog, tapi entri changelog ditulis sekali sementara deprecation dilacak sampai sunset-nya. Menggabungkan keduanya adalah alasan mengapa sunset terlewat.

Apa yang masuk dalam satu entri?

Enam hal, dan tiga yang pertama biasanya yang hilang. Perubahan itu sendiri, dinyatakan dalam istilah request atau response, bukan komponen internal. Apakah itu merusak pemanggil yang benar. Apa yang harus dilakukan pemanggil, termasuk “tidak ada”. Tanggal berlakunya. Versi atau versi-versi yang terdampak. Tautan ke panduan migrasi jika ada.

Entri yang mengatakan “endpoint accounts ditingkatkan” gagal pada keenamnya. Entri yang mengatakan “field accounts.type sekarang mengembalikan individual di mana sebelumnya mengembalikan personal; nilai yang sudah ada tidak berubah untuk akun yang dibuat sebelum 2 September; tidak perlu tindakan kecuali Anda membandingkan string” menjawab keenamnya dalam satu kalimat.

Kategorikan entri berdasarkan konsekuensi, bukan departemen. Tiga label membawa hampir seluruh nilainya: breaking, additive, dan fixed. Semantic Versioning sudah mendefinisikan dua yang pertama secara tepat, dan meminjam definisinya alih-alih menciptakan yang lokal berarti pembaca yang tahu semver tahu label Anda. Keep a Changelog menawarkan set yang lebih panjang jika Anda mau, dan aturan intinya berlaku di sini lebih kuat daripada di tempat lain: log itu untuk manusia, dan tumpukan judul commit bukanlah itu.

Apa bedanya changelog API dengan release notes?

Release notes menjelaskan apa yang bisa dilakukan produk sekarang. Changelog API menjelaskan apa kontraknya sekarang. Pekerjaan yang sama yang dirilis sering menghasilkan entri di keduanya, dirumuskan berbeda, karena audiensnya butuh hal yang berbeda: format ekspor baru adalah fitur bagi pengguna dan nilai enum baru bagi pemanggil yang bergantung pada field itu.

Konsekuensi praktisnya adalah keduanya tidak bisa menjadi feed yang sama dengan gaya berbeda. Pemanggil yang berlangganan segala yang Anda rilis akhirnya akan berhenti berlangganan, lalu melewatkan breaking change. Jika Anda menerbitkan satu feed, saring; jika menerbitkan dua, buat yang API lebih sempit dan jangan pernah biarkan entri marketing masuk ke dalamnya. Kami membandingkan kedua bentuk berdampingan di changelog vs release notes.

Di mana changelog API sebaiknya berada?

Di samping dokumentasi referensi, di URL yang stabil, dengan setiap entri dapat dialamatkan secara individual lewat fragment atau path-nya sendiri. Pemanggil menautkan entri dalam tinjauan insiden dan tiket internal, dan entri yang tidak bisa ditautkan akan ditempel sebagai screenshot sebagai gantinya.

Terbitkan juga sebagai output yang bisa dibaca mesin, selain sebagai halaman. Feed JSON yang mengikuti spesifikasi JSON Feed atau feed RSS tidak memakan biaya apa pun begitu entri menjadi data terstruktur, dan itulah yang memungkinkan pelanggan memasukkan perubahan Anda ke proses rilis mereka sendiri. Ini juga bagian yang menentukan apakah ada yang membangun di atasnya. GitHub mendokumentasikan versi REST API-nya tepat di samping referensi dengan alasan yang sama: kebijakan versi adalah bagian dari antarmuka.

Seperti apa entri yang baik dalam praktiknya?

Tiga entri dari minggu yang sama, dalam bentuk yang dijelaskan di atas:

2026-09-02  Breaking  v2
  `POST /invoices` sekarang menolak `currency` yang tidak cocok dengan
  mata uang akun pelanggan, mengembalikan 422 alih-alih mengonversi
  secara diam-diam. Pemanggil yang mengandalkan konversi harus mengirim
  mata uang akun. Hanya memengaruhi v2; v1 tidak berubah hingga
  sunset-nya pada 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` mendapat timestamp `settled_at`, null hingga faktur
  dilunasi. Tidak perlu tindakan. Client yang menolak field tak
  dikenal sebaiknya diperbarui.

2026-08-31  Fixed  v2
  `GET /invoices?status=` mengembalikan halaman kosong alih-alih 400
  untuk status yang tidak dikenal. Sekarang mengembalikan 400 dengan
  nilai yang diterima. Pemanggil dengan salah ketik sebelumnya melihat
  nol hasil, sekarang melihat error.

Yang ketiga adalah jenis yang paling sering dihilangkan, karena secara internal itu adalah perbaikan bug. Bagi pemanggil yang membangun retry di sekitar halaman kosong itu, ini adalah perubahan perilaku, dan entri itulah yang mencegah tiket support. Labelnya mengatakan fixed dan isinya mengatakan apa yang mungkin diperhatikan pemanggil, yang merupakan pembeda yang menjaga log tetap jujur tanpa menggembungkan setiap perbaikan menjadi breaking change.

Bagaimana pemanggil berlangganan?

Berikan mereka lebih dari satu kanal, karena tugas mereka berbeda. Feed untuk developer yang menginginkan semuanya. Email untuk yang hanya menginginkan breaking change. Header response untuk kode itu sendiri, satu-satunya pelanggan yang tidak pernah lupa memeriksa: header Sunset yang didefinisikan di RFC 8594 menempatkan tanggal pensiun di response, tempat library client bisa mencatatnya.

Kanal yang paling sering dilewatkan kebanyakan tim adalah yang langsung. Jika seorang pemanggil menggunakan field yang sedang Anda ubah minggu lalu, Anda tahu siapa dia, dan email ke akun-akun itu lebih berharga daripada siaran sebanyak apa pun. Ini adalah disiplin yang sama dengan menutup loop feedback pelanggan, diterapkan pada perubahan yang tidak diminta siapa pun: orang yang terdampak diberi tahu satu per satu, dan semua yang lain mendapat feed. Webhook adalah kanal keempat dengan mode kegagalannya sendiri yang layak diketahui sebelum mengandalkannya: changelog webhook membahas mengapa perubahan payload di sana rusak diam-diam, tanpa pemanggil yang bisa menolak bentuk barunya.

Bagaimana cara menulis entri untuk breaking change?

Mulai dengan kerusakannya, bukan alasannya. Pemanggil yang memindai sepuluh entri perlu tahu di klausa pertama apakah entri ini akan menghabiskan waktunya. Lalu tanggal, versi yang terdampak, migrasi, dan tenggat waktu jika perilaku lama akan hilang alih-alih berubah.

Masukkan konten yang sama ke pemberitahuan deprecation, header response, dan email langsung, dirumuskan secara konsisten, dan beri keempatnya tanggal yang sama. Perbedaan di antara mereka adalah kegagalan yang mengubah perubahan terencana menjadi insiden, karena pemanggil yang hanya membaca satu darinya bertindak berdasarkan tanggal yang salah. Apa itu breaking change membahas keputusannya sendiri, dan cara men-deprecate API membahas jadwal yang mengikutinya.

Di changeloop, perubahan API menjadi entri saat pull request digabungkan, seseorang mengedit dan menyetujui draf, dan entri diterbitkan ke feed dan widget pada saat yang sama pemanggil yang masukan widget-nya menjadi issue GitHub yang ditutup oleh pull request itu diberi tahu di issue tersebut. Langkah peninjauan adalah yang penting di sini: changelog API adalah dokumen kontraktual, dan tidak ada draf yang boleh sampai ke pemanggil tanpa dibaca oleh seseorang.

FAQ

Apakah setiap perubahan API perlu entri changelog? Setiap perubahan yang mungkin diperhatikan pemanggil yang benar, ya, termasuk yang Anda anggap internal. Perubahan tanpa efek yang bisa diamati pada request atau response tidak, dan menambahkannya melatih pembaca untuk hanya melirik.

Sebaiknya changelog API berada di docs atau di situs marketing? Di docs, tepat di samping referensi. Pembaca biasanya sudah ada di sana, dan changelog di situs marketing cenderung mendapat audiens yang bukan tujuan penulisannya.

Seberapa jauh ke belakang seharusnya? Tanpa batas. Entri dikutip bertahun-tahun kemudian dalam tinjauan insiden, dan log yang dipotong merusak tautan itu. Gunakan paginasi alih-alih memangkas.

Apakah saya perlu changelog terpisah per versi API? Tidak, satu log dengan field versi per entri lebih mudah dibaca dan dicari. Menyaring berdasarkan versi adalah fitur halaman, bukan alasan untuk memisahkan dokumen.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Dokumentasi developer, Contoh changelog