Cara menulis panduan migrasi API

Panduan migrasi API adalah dokumen yang mengubah perubahan tak kompatibel menjadi checklist, bukan gangguan: apa yang berubah, apa yang harus dilakukan, dan sampai kapan. Entri changelog bisa menyebutkan perubahan tak kompatibel dalam dua kalimat; panduan migrasi adalah yang benar-benar dibuka pemanggil ketika dua kalimat itu berkata “ini merusak Anda” dan mereka perlu tahu persis apa yang harus diedit. Mempublikasikan entri tanpa panduan adalah cara pemanggil mengetahui perubahan tak kompatibel dari tiket dukungan alih-alih dari dokumen yang ditulis untuk mencegahnya.

Apa itu panduan migrasi API?

Dokumen langkah demi langkah yang membawa pemanggil dari bentuk lama API ke yang baru, ditulis untuk seseorang dengan kode yang harus diubah, bukan seseorang yang masih memutuskan apakah akan mengadopsi API. Perbedaan itu penting: panduan migrasi mengasumsikan integrasi yang sudah ada dan lalu lintas produksi yang sudah ada, jadi harus mencakup rollback, migrasi parsial, dan cara mengetahui apakah migrasi berhasil, semua yang tidak dibutuhkan panduan integrasi pertama.

Panduan migrasi biasanya berada di antara dua yang terakhir: pemberitahuan deprecation memulai jam, dan panduan migrasi adalah yang diikuti pemanggil sebelum jam itu habis.

Kapan sebuah perubahan butuh panduan migrasi, bukan hanya entri changelog?

Ketika ada lebih dari satu langkah antara perilaku lama dan baru, atau ketika perubahan menyentuh cukup banyak titik pemanggilan sehingga pemanggil lebih diuntungkan oleh contoh yang dikerjakan daripada deskripsi. Apa itu perubahan tak kompatibel, dan cara merilisnya membahas uji apakah perubahan itu tak kompatibel; jika jawabannya ya, pertanyaan kedua adalah apakah perbaikannya adalah edit satu baris atau migrasi sungguhan. Kolom yang diganti nama bisa ditangani pemanggil hanya dengan entri changelog. Perubahan pada autentikasi, paginasi, atau penanganan error hampir selalu pantas mendapat panduan, karena kode pengganti yang benar tidak jelas dari deskripsi satu kalimat.

Apa yang harus dimuat panduan migrasi?

Lima hal, dan melewatkan salah satunya adalah cara panduan berubah menjadi halaman yang dibaca pemanggil sekali lalu kembali ke coba-coba. Kode lama, ditampilkan seperti yang sebenarnya muncul dalam proyek. Kode baru, ditampilkan dengan cara yang sama, bukan sebagai deskripsi abstrak perbedaannya. Apa yang rusak jika tak ada yang diubah, dikatakan dengan jelas, karena “tidak ada” adalah jawaban yang valid dan umum yang tetap perlu didengar pemanggil secara eksplisit. Cara memverifikasi migrasi berhasil, seperti kolom respons atau kode status untuk dicek. Dan jadwal: kapan perilaku lama berhenti berfungsi, dan apakah kedua bentuk tersedia sementara itu.

## Migrasi kolom mata uang dari float ke integer (v3.0.0)

Sebelum:
  { "amount": 19.99 }

Sesudah:
  { "amount": 1999 }  // unit mata uang terkecil (sen)

Yang berubah: `amount` sekarang adalah bilangan bulat dalam unit
terkecil mata uang akun. Kode yang membaca `amount` sebagai float
akan membaca nilai 100x terlalu besar mulai 1 Oktober 2026.

Verifikasi: setelah migrasi, tagihan $19.99 harus terbaca sebagai
`amount: 1999`, bukan `amount: 19.99`.

Jadwal: v2 tetap mengembalikan float sampai 15 Januari 2027. v3
mengembalikan bilangan bulat sejak peluncuran. Kedua versi aktif
sekarang.

Setiap dari lima hal itu menjawab pertanyaan yang jika tidak, harus ditebak atau ditanyakan pemanggil ke dukungan, dan itulah biaya sesungguhnya yang dihemat panduan migrasi.

Siapa yang harus menulisnya, dan kapan?

Siapa pun yang merancang perubahan, pada saat yang sama ketika dirilis, bukan tim dukungan yang merekonstruksinya dari tiket belakangan. Yang membuat keputusan tahu bagian mana dari perilaku lama yang seharusnya tidak diandalkan siapa pun dan mana yang merupakan kontrak tak sengaja; panduan yang ditulis belakangan oleh seseorang tanpa konteks itu cenderung terlalu menjelaskan yang jelas atau melewatkan satu kasus tepi yang benar-benar merusak orang. Panduan dan entri changelog yang mengumumkan perubahan tak kompatibel sebaiknya dirilis bersamaan, dengan entri menautkan ke panduan alih-alih mengulanginya.

Bagaimana ini berkaitan dengan versioning dan changelog API?

Secara langsung: panduan migrasi adalah versi rinci dari yang hanya diringkas dalam satu kalimat oleh entri MAJOR di semantic versioning dan changelog Anda. Entri changelog mengatakan perubahan tak kompatibel dan garis besar apa yang berubah; panduan migrasi adalah tautan yang seharusnya dibawa entri itu. Changelog API: apa yang dipublikasikan dan siapa yang membacanya mencantumkan panduan migrasi sebagai salah satu dari lima dokumen yang dipelihara API, masing-masing menjawab pertanyaan berbeda; ini adalah yang menjawab “bagaimana saya benar-benar pindah dari A ke B”, dan pantas mendapat halamannya sendiri justru karena jawaban itu biasanya terlalu panjang untuk entri changelog.

Berapa lama panduan migrasi harus tetap dipublikasikan?

Setidaknya selama perilaku lama masih bisa dijangkau, dan idealnya juga setelahnya. Pemanggil yang bermigrasi terlambat delapan belas bulan, setelah mengabaikan tiga pemberitahuan deprecation, masih membutuhkan panduan, dan menghapusnya pada hari perilaku lama dimatikan hanya menjamin pemanggil yang paling membutuhkannya tidak menemukannya. Simpan di URL yang stabil dan perbarui bagian jadwal alih-alih menarik halaman. Panduan peningkatan milik Stripe sendiri adalah contoh publik dari pola ini: satu halaman yang tetap terkini dari rilis ke rilis, bukan dokumen baru per versi yang basi begitu versi berikutnya rilis. Panduan Anda sendiri layak mendapat tempat yang sama mudah ditemukannya, di samping dokumentasi yang sudah dibaca pemanggil, alih-alih terkubur di arsip blog.

FAQ

Apakah setiap perubahan tak kompatibel butuh panduan migrasi? Tidak. Perubahan yang bisa ditangani pemanggil hanya dengan entri changelog, seperti satu kolom yang diganti nama dengan pengganti yang jelas, tidak butuh panduan terpisah. Perubahan yang menyentuh beberapa titik pemanggilan atau butuh contoh yang dikerjakan, ya.

Haruskah panduan migrasi berada bersama dokumentasi API atau di changelog? Bersama dokumentasi, ditautkan dari entri changelog. Entri adalah yang dilihat pelanggan lebih dulu; panduan adalah yang dibutuhkan begitu mereka memutuskan untuk bertindak, dan tempatnya di sebelah materi referensi yang sudah dipakai pemanggil.

Apa bedanya panduan migrasi dengan pemberitahuan deprecation? Pemberitahuan deprecation menyatakan sesuatu akan hilang dan sampai kapan. Panduan migrasi adalah instruksi apa yang harus dilakukan soal itu. Pemberitahuan deprecation tanpa panduan migrasi yang ditautkan memberi pemanggil tenggat tanpa memberitahu cara memenuhinya.

Haruskah perilaku lama dan baru sama-sama didokumentasikan selama jendela migrasi? Ya, di halaman yang sama jika memungkinkan, sehingga pemanggil melihat persis apa yang berubah alih-alih menyusunnya dari dua dokumen terpisah yang ditulis pada waktu berbeda.

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