Deprecate a web API: Best Practices?

Akhirnya Anda perlu mendepresiasi bagian-bagian dari API web publik Anda. Namun saya bingung bagaimana cara terbaik untuk melakukannya. Jika Anda memiliki basis aplikasi pihak ke-3 yang besar hanya menyentak versi lama dari API sepertinya cara yang salah untuk melakukannya karena hampir semua aplikasi akan gagal dalam semalam. Namun Anda tidak dapat menyimpan api web kuno selamanya karena mungkin sudah ketinggalan zaman atau ada perubahan signifikan yang membuat bekerja dengannya tidak mungkin.

Apa sajakah praktik terbaik untuk mencabut api web lama?

Kedengarannya seperti poster asli sudah efektif, tetapi secara informal mencabut API mereka (apa pun yang disebut sebagai 'API lama'). Namun, sampai diumumkan dan pengguna diberitahukan bahwa suatu API sudah tidak digunakan lagi, itu tidak akan secara resmi ditinggalkan.

API yang tidak digunakan lagi adalah tahap kode sementara yang tidak aktif. Ini adalah ritual terakhir. Ini adalah periode yang memungkinkan pengadopsi / konsumen untuk mengkonfigurasi ulang aplikasi mereka untuk API yang lebih baru dan mengucapkan selamat tinggal, membuat perdamaian dengan API. Beberapa API mungkin bertahan lebih lama dari yang lain, tetapi pada titik ini kita tahu waktunya tidak lama.

API yang dihapus adalah pemakaman kode. Tidak ada lagi yang bisa dilakukan, tetapi dibuang dengan benar dan diabadikan dengan tepat.

Banyak API dan pengembang layanan memilih pemakaman kode daripada melakukan ritual terakhir; Namun, saya pikir itu agak berisiko. Jika ada jenis layanan atau janji dukungan yang dibuat ketika API / layanan awalnya diadopsi atau melalui pembaruan, Anda mungkin ingin menghormati komitmen itu untuk jangka waktu yang wajar sebelum melakukan pemakaman.

Untuk perpustakaan non-layanan, saya pikir satu versi rilis utama, terlepas dari periode waktu, mungkin lebih dari periode yang dapat diterima dan adil kompatibilitas mundur. Di luar itu tergantung pada pengaruh dan lobi oleh pengguna untuk memperpanjang umurnya di luar periode itu. Dan jangan heran jika dari waktu ke waktu ada keberatan karena ketergantungan pihak ketiga yang tidak dapat diperbaiki terjebak dalam limbo, dan terikat pada versi tertentu dari platform tertentu.

Untuk layanan, saya menduga Anda mungkin ingin melihat periode enam bulan atau tahun, hanya karena perbedaan dalam oleh siapa dan bagaimana layanan dapat dikonsumsi, dan varian siklus pengembangan yang sesuai dari proyek konsumsi ke proyek konsumsi - banyak proyek yang mungkin memakan layanan Anda masih bisa desain awal yang besar, dan mungkin menjadwalkan siklus rilis lebih dari satu tahun. Sebagian besar pendapat pengembang dari luar akan menyarankan bahwa mereka yang memiliki jadwal panjang bertanggung jawab untuk memenuhi waktu siklus Anda, dan proyek-proyek yang memakan waktu yang lama harus mengadopsi siklus rilis yang lebih cepat, dan itu mungkin benar. Tetapi pada akhirnya tanggal penghapusan adalah sesuatu yang harus Anda negosiasikan dengan pengguna.

Strategi yang bagus tapi tidak tahan banting untuk penghentian mungkin ketika mengumumkan penghentian, sorot jangka waktu untuk niat untuk menghapus, bersama dengan permintaan untuk komentar atau keberatan dalam format survei dari bagian API yang bersangkutan. Jika Anda tidak memiliki daftar kontak pengguna karena layanan Anda beroperasi dengan [semi] akses anonim, Anda dapat mempertimbangkan melihat log untuk pengguna yang sering dan aktif dan mengirimkan pemberitahuan ke host atau administrator domain untuk meneruskan sesuai keinginan mereka.

Sebagian besar API Web yang saya gunakan (dari perusahaan seperti Google, Yahoo! dan Microsoft) memiliki periode "matahari terbenam". Pengembang diinformasikan dalam waktu yang wajar (katakanlah 3-6 bulan) dari fitur yang akan didepresiasi untuk memberi mereka banyak waktu untuk meningkatkan versi sebelumnya.

Anda dapat menambahkan rincian periode matahari terbenam dalam Ketentuan Layanan Anda atau dokumentasi lain sehingga orang-orang mengetahui cara kerjanya. Ini berarti bahwa ketika seseorang memutuskan untuk menggunakan API Anda, mereka akan tahu jadwal apa yang mereka butuhkan untuk bekerja. Misalnya, Anda dapat memberi tahu orang-orang bahwa mereka perlu memutakhirkan sistem mereka setahun sekali dan memiliki pemberitahuan 4 bulan untuk melakukannya.

Ini juga merupakan ide yang baik untuk menggunakan penomoran versi sehingga Anda dapat mengatakan bahwa, misalnya, "versi 3 akan segera disusutkan jadi pastikan kode Anda berfungsi dengan versi 4" dll. Dengan begitu orang tahu bahwa jika aplikasi mereka bekerja dengan versi 4 maka mereka siap untuk matahari terbenam.

Informasi tambahan dari sudut proses:

• Berkomunikasi dengan semua pemangku kepentingan : Berikan komunikasi yang jelas dan ringkas kepada tim lain dan konsumen API tentang alasan penghentian API, strategi, detail rencana dan jadwal, makna versi, dan alternatif, atur HTTP sesuai.

• Paket dan Rencana : Pada paket tersebut Anda harus memiliki tonggak utama dan tanggal target untuk akhir penghentian. Anda harus meminta konsumen untuk hal yang sama dan memberikan tanggal kapan mereka akan membatalkan panggilan. Tuan rumah pertemuan rutin untuk memantau proses dan mendukung konsumen.

• Versi dan Menyediakan Alternatif : Versi ini dapat membantu untuk menunjukkan perubahan istirahat pada rilis utama, dan membuat strategi depresiasi API.

• Mengatur Sunset HTTP Header Header : Header HTTP memainkan bagian teknis dari peringatan, konsumen API harus memantau jenis kode ini untuk memahami kapan API semakin ditinggalkan.

• Monitor Sebelum dan Sesudah : Monitor konsumen Anda dan beri tahu konsumen yang masih menggunakan API setelah periode tertentu adalah informasi yang berguna untuk memastikan Anda tidak ketinggalan perangkat yang ditinggalkan.

Selain jawaban yang ada, Anda harus memberikan pengganti atau rencana migrasi saat menghapus sesuatu, sehingga pengguna Anda dapat memperbarui kode mereka.

Cobalah untuk menghindari penghapusan fungsionalitas tanpa memberikan alternatif - ini akan membuat beberapa pengguna Anda tidak bahagia.