Petunjuk dan ruang lingkup
Penyedia ingin menghapus /v1/items setelah jendela migrasi, tetapi klien dimiliki oleh tim yang berbeda dan beberapa di antaranya tidak aktif (dormant). Asumsikan penyedia dapat mengamati permintaan berdasarkan identitas klien dan dapat menjalankan /v2/items secara paralel. Rencana tersebut harus membedakan pengumuman deprecation dari tanggal penghapusan, mempertahankan fallback yang aman, dan menghindari asumsi bahwa header saja dapat memigrasikan klien.
Hal yang diuji oleh pewawancara
- Memisahkan sinyal protokol, dokumentasi, inventaris klien, dan penegakan (enforcement).
- Merancang kompatibilitas aditif dan gerbang migrasi (migration gate) yang terukur.
- Menangani klien yang tidak dikenal, integrasi yang sudah lama berjalan, dan rollback darurat.
- Memilih kode status dan header tanpa menciptakan semantik di luar standar.
Pertanyaan klarifikasi yang perlu diajukan
Tanyakan apakah klien mengirimkan identitas yang stabil, apakah /v2 dapat bersifat aditif, periode dukungan minimum, persyaratan pemberitahuan kontraktual, dan apakah endpoint lama dapat dijadikan read-only sebelum dihapus. Jika identitas tidak tersedia, bukti migrasi harus berasal dari kredensial, metadata jaringan, atau pendaftaran eksplisit alih-alih menebak user agent.
Jawaban 30 detik
Saya akan menginventarisasi pemanggil, menerbitkan panduan migrasi berversi, merilis /v2 secara aditif, serta mengukur lalu lintas per klien dan paritas kesalahan. Tandai /v1 dengan sinyal Deprecation standar dan tanggal Sunset, sembari menampilkan dasbor dan pemberitahuan langsung untuk pemilik yang dikenal. Pertahankan jalur lama selama jendela waktu yang ditentukan, berlakukan penegakan hanya setelah melewati gerbang bukti, dan kembalikan respons terminal terdokumentasi yang berisi tautan migrasi. Feature flag dan perutean yang dapat dibalik (reversible routing) menyediakan rollback jika klien penting mengalami gangguan.
Pembahasan mendalam langkah demi langkah
1. Menetapkan kompatibilitas dan bukti
Definisikan perbedaan tingkat field, perilaku default, paginasi, error, dan perubahan autentikasi. Jalankan pengujian kontrak terhadap kedua versi dan bandingkan respons representatif. Beri tag metrik berdasarkan klien, versi, endpoint, status, dan status migrasi; jangan hanya menggunakan lalu lintas agregat karena klien bervolume rendah mungkin sangat penting bagi bisnis.
2. Memberikan sinyal deprecation secara presisi
Header respons Deprecation mengomunikasikan bahwa suatu sumber daya telah didepresiasi; header Sunset mengomunikasikan tanggal terencana setelah itu sumber daya mungkin tidak lagi tersedia. Ini hanyalah sinyal, bukan jaminan bahwa setiap klien memahaminya. Ulangi tanggal tersebut dalam dokumentasi dan pemberitahuan pemilik, serta sertakan referensi migrasi yang stabil di dalam body respons atau relasi tautan yang ditentukan oleh kontrak API.
3. Migrasi dan penegakan secara bertahap
Mulailah dengan peringatan dan dasbor, lalu wajibkan pengecualian eksplisit untuk klien yang melewati batas waktu target. Tawarkan perbandingan bayangan (shadow comparison) atau lalu lintas keikutsertaan (opt-in) sebelum mengalihkan default. Pada gerbang penegakan, tolak hanya operasi lama yang aman untuk dihentikan, kembalikan error yang dapat dibaca mesin, dan pertahankan jalur dukungan. Kompatibilitas read-only dapat diperpanjang lebih lama daripada kompatibilitas mutasi jika risikonya berbeda.
4. Menjaga rollback dan tata kelola tetap nyata
Simpan tanggal sunset, pemilik, alasan pengecualian, dan persetujuan dalam catatan perubahan (change record). Berikan peringatan untuk delta kesalahan pascamigrasi dan permintaan dari klien yang tidak dikenal. Rutekan jalur lama melalui feature flag sehingga rollback hanyalah perubahan konfigurasi, bukan deploy ulang kode. Setelah penghapusan, pertahankan telemetri dan respons tombstone cukup lama untuk menjelaskan kegagalan tanpa mengekspos rahasia.
Contoh jawaban yang kuat
Saya akan menginventarisasi 10.000 pemanggil dan menentukan perbedaan kontrak yang tepat antara /v1 dan /v2. Kedua versi berjalan secara paralel dengan metrik per klien dan pengujian kontrak. Respons /v1 membawa sinyal Deprecation dan Sunset, sementara dokumentasi dan pemberitahuan pemilik mengulangi tanggal dan langkah migrasi. Penyedia bergerak melalui tahap peringatan, opt-in, default ke v2, dan penegakan, dengan pengecualian eksplisit dan error terminal yang dapat dibaca mesin. Feature flag menjaga rollback tetap memungkinkan; gerbang sunset didasarkan pada bukti tingkat klien, bukan persentase lalu lintas agregat.
Kesalahan umum
- Menganggap header dapat melakukan migrasi sendiri → banyak klien mengabaikannya → pasangkan sinyal standar dengan penemuan pemilik dan panduan.
- Menetapkan tanggal tanpa inventarisasi → klien yang tidak aktif tetapi penting tiba-tiba gagal → wajibkan identitas klien dan peninjauan pengecualian.
- Hanya membandingkan tingkat kesalahan agregat → gangguan pada satu tenant hilang dalam rata-rata → pantau paritas dan volume per klien.
- Menghapus segera setelah
/v2dirilis → klien tidak memiliki bukti kompatibilitas → jalankan tahap paralel atau opt-in terlebih dahulu. - Menjadikan rollback sebagai deploy ulang → pemulihan lambat saat terjadi outage → rutekan versi di balik flag yang dapat dibalik.
- Mengembalikan 404 yang tidak terdokumentasi saat sunset → otomatisasi tidak dapat membedakan penghapusan dari kesalahan ketik (typo) → publikasikan error terminal yang stabil dan referensi migrasi.
Pertanyaan lanjutan dan tanggapan
Klien tidak pernah mengirimkan header identifikasi. Apa yang menjadi gerbang migrasi?
Gunakan kredensial, akun, jaringan, atau identitas pendaftaran yang sudah tersedia bagi penyedia. Jika tidak ada yang dapat diandalkan, biarkan endpoint tersedia lebih lama dan wajibkan pendaftaran eksplisit sebelum penegakan.
Bisakah tanggal Sunset diundur?
Ya, jika catatan perubahan, dokumentasi, header, dan pemberitahuan pemilik diperbarui bersamaan. Perlakukan tanggal tersebut sebagai komitmen tata kelola dan beri peringatan untuk klien yang masih bergantung pada jalur lama.
Bagaimana jika /v2 benar tetapi lebih lambat untuk satu klien?
Bandingkan latensi dan anggaran kesalahan (error budget) klien tersebut secara terpisah, lalu optimalkan atau berikan pengecualian dengan batas waktu. Jangan memperpanjang jendela sunset untuk seluruh populasi tanpa bukti bahwa masalah tersebut bersifat sistemik.
Bagaimana cara menghentikan endpoint yang melakukan mutasi dengan aman?
Hentikan penulisan baru setelah gerbang bukti, pertahankan akses baca jika memungkinkan, dan buat percobaan ulang mengembalikan error terminal yang deterministik. Pastikan antrean downstream dan catatan audit tidak lagi bergantung pada mutasi lama sebelum penghapusan.