Header sunset API, dan kapan mengirimkannya

Sunset adalah satu header respons tunggal, didefinisikan dalam RFC 8594, yang memberi tahu pemanggil kapan sebuah resource akan berhenti merespons. Deprecation API membahas seluruh linimasa umumkan-ingatkan-brownout-pensiunkan beserta pemberitahuan yang menyertainya; ini tentang satu sinyal yang bisa dibaca mesin dalam linimasa itu, apa sebenarnya yang dikatakannya, dan satu kasus ketika RFC sendiri mengatakan untuk tidak mengirimkannya.

Apa yang dikatakan header Sunset, dan apa yang tidak dikatakannya?

Header ini membawa satu tanggal-HTTP, titik waktu ketika resource diperkirakan berhenti merespons:

Sunset: Sat, 31 Dec 2028 23:59:59 GMT

RFC menyebutnya sebagai petunjuk, bukan jaminan: header ini tidak menjanjikan resource akan tetap berfungsi persis sampai stempel waktu itu, dan tidak mengatakan apa pun tentang seperti apa kegagalannya nanti. Pemanggil bisa mendapat 4xx, redirect, atau tidak ada respons sama sekali; header tidak membedakannya. Stempel waktu yang sudah lewat berarti “sekarang, atau kapan saja” alih-alih kesalahan pada nilainya. Tidak satu pun dari ini dipaksakan oleh protokol. Klien yang tidak pernah membaca header ini berperilaku persis seperti biasanya, dan tetap mengetahui resource sudah hilang dengan cara yang sama seperti yang akan terjadi tanpa header ini.

Kapan sebenarnya Anda harus mengirimkannya?

Hanya setelah resource benar-benar akan berhenti merespons, bukan ketika ia sekadar tidak lagi jadi pilihan yang direkomendasikan. RFC secara eksplisit menyatakan deprecation terjadi dalam dua tahap, dan field header Sunset hanya berlaku untuk tahap kedua: API tetap beroperasi penuh selama tahap pertama, yaitu pengumuman bahwa suatu versi tidak lagi diutamakan, dan field header ini tidak berlaku di sana. Ia berlaku begitu versi tersebut benar-benar dijadwalkan berhenti merespons.

Itu berpadanan langsung dengan linimasa deprecation: header Deprecation dikirim sejak hari pertama, pada langkah pengumuman; Sunset menjelaskan tanggal perilaku lama akan benar-benar berhenti, yaitu tanggal yang sama yang disebut linimasa empat langkah sebagai pensiun. Mengirim Sunset pada hari pertama tidak salah, karena tanggalnya sudah pasti saat itu, tapi mengirimkannya tanpa juga mengumumkan deprecation, atau menetapkannya untuk versi yang belum benar-benar Anda komit untuk dipensiunkan, memberi tahu pemanggil sesuatu yang belum Anda putuskan.

Apakah ini berinteraksi dengan caching?

Tidak, dan RFC mengatakannya secara langsung: Sunset dan HTTP caching menyelesaikan masalah yang tidak berhubungan dan harus dibaca sebagai saling melengkapi, bukan tumpang tindih. Header caching mengatakan kapan salinan cache aman digunakan ulang; Sunset tidak mengatakan apa pun tentang keadaan resource saat ini, hanya bahwa resource itu sendiri akan berhenti ada. Sebuah respons bisa sepenuhnya bisa di-cache sampai persis saat ia sunset. Jangan gunakan salah satu untuk mendekati yang lain, dan jangan asumsikan max-age yang panjang meniadakan tanggal sunset yang mendekat, atau sebaliknya.

Bisakah satu header men-sunset lebih dari satu endpoint?

Header ini berlaku untuk resource yang mengembalikannya, tapi RFC mengizinkan sebuah layanan mendokumentasikan cakupan yang lebih luas: tanggal Sunset pada resource utama sebuah API bisa didefinisikan berarti seluruh API akan hilang, bukan hanya satu URL itu. Jebakannya adalah ini hanya berfungsi untuk pemanggil yang sudah tahu aturan cakupan Anda. Pemanggil yang membaca header apa adanya hanya melihat sunset pada satu resource yang ia minta dan tidak ada yang lain, jadi cakupan yang lebih luas harus dituliskan di suatu tempat yang bisa ditemukan pemanggil, bukan tersirat.

Apa yang harus menyertai header ini?

Tautan ke tempat pensiun ini dijelaskan. RFC 8594 mendaftarkan relasi tautan sunset miliknya sendiri untuk keperluan ini: menunjuk ke resource yang menjelaskan kebijakan pensiun, tanggal yang akan datang, atau cara bermigrasi, terpisah dari stempel waktu polos pada header.

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2028 23:59:59 GMT
Link: <https://example.com/docs/sunset-policy>; rel="sunset"

Mengarahkan tautan itu ke contoh changelog Anda sendiri atau halaman migrasi khusus mengubah header yang nyaris tidak diperiksa kode klien siapa pun menjadi sesuatu yang langsung ditemukan manusia yang benar-benar mencarinya. Gabungkan dengan relasi successor-version dari header deprecation dan pemanggil mendapat baik ke mana harus pergi maupun apa yang menggantikan ini, hanya dari respons itu sendiri.

Seperti apa ini dari ujung ke ujung?

Misalkan v1 akan hilang pada 1 Maret 2027. Pengumuman deprecation pada hari pertama menambahkan Deprecation dan Link: rel="successor-version" ke setiap respons v1, sesuai header deprecation, tapi menahan Sunset sampai tanggal pensiun benar-benar pasti, bukan sekadar placeholder. Begitu pasti, setiap respons v1 membawa:

HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/docs/sunset-policy>; rel="sunset"

Gateway atau monitoring milik pemanggil bisa memicu peringatan pada salah satu header secara independen: Deprecation mengatakan versi yang lebih baru ada, Sunset mengatakan yang ini punya batas waktu. Tidak ada header yang wajib berubah sebelum 1 Maret; yang berubah adalah respons itu sendiri, pada harinya, dan selama jendela brownout mana pun yang dijadwalkan sebelumnya.

Apakah brownout mengubah isi header?

Nilai header itu sendiri tidak perlu berubah untuk brownout yang dijadwalkan: tanggal sunset tetaplah tanggal sunset, terlepas dari apakah resource sesekali gagal sebelum itu. Yang berubah adalah respons, bukan headernya. Menjadwalkan jendela singkat 410 Gone di minggu-minggu sebelum tanggal yang diumumkan, seperti dijelaskan Deprecation API, adalah yang mengubah kontak pertama pemanggil dengan kegagalan menjadi gladi bersih alih-alih kejadian sungguhan pada hari tanggal header itu tiba.

FAQ

Apakah ada klien atau tool HTTP nyata yang benar-benar membaca header Sunset? Jarang, di sisi klien. Nilainya sebagian besar untuk siapa pun yang mengoperasikan infrastruktur di antara Anda dan pemanggil: gateway API atau tool monitoring yang Anda konfigurasi untuk memantau header ini bisa memperingatkan tim Anda sendiri, atau tim mitra, jauh sebelum kode pemanggil menyadarinya. Perlakukan ini sebagai sinyal yang Anda bangun tooling-nya, bukan sesuatu yang bisa Anda asumsikan sudah dimiliki pihak lain.

Apakah Sunset sama dengan Cache-Control: max-age? Tidak. max-age mengatur berapa lama salinan cache tetap valid; Sunset mengatur kapan resource berhenti ada sama sekali. Sebuah respons bisa membawa max-age yang pendek dan tanggal Sunset yang masih bertahun-tahun lagi, atau sebaliknya, dan tidak ada header yang membatasi yang lain.

Bisakah saya mengirim Sunset untuk satu field yang hilang, bukan seluruh endpoint? Tidak, header ini dicakup pada resource, artinya URL, bukan pada field di dalam isi responsnya. Untuk field, parameter, atau nilai enum yang akan hilang sementara endpoint-nya sendiri tetap aktif, gunakan header Deprecation dan entri changelog sebagai gantinya; Deprecation API membahas cara mengumumkan perubahan semacam itu persis.

Bagaimana jika tanggal sunset perlu digeser? Perbarui nilai headernya dan katakan itu di entri changelog yang pertama kali mengumumkannya; mengubah tanggal yang sudah dipublikasikan secara diam-diam adalah cara pemanggil memutuskan bahwa tidak satu pun tanggal Anda nyata. RFC membingkai nilai ini sebagai petunjuk justru karena tanggal memang kadang bergeser, tapi tanggal yang digeser tanpa penjelasan membuat Anda kehilangan kepercayaan untuk tanggal berikutnya juga.

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