Deprecation
Bird mendeprekasi tiga hal berbeda, dan masing-masing berperilaku berbeda. Request field diganti namanya, dan nama lama tetap berfungsi berdampingan dengan nama baru. Query parameter digantikan oleh filter yang lebih baik, dan tetap berfungsi tanpa perubahan. Request body shape digantikan oleh bentuk baru, dan bentuk lama tetap diterima. Dalam semua kasus, request yang menggunakannya mendapat header respons Deprecation sebagai pemberitahuan.
Header
Respons terhadap request yang membawa field, parameter, atau body shape yang dideprekasi menyertakan:
| Header | Nilai |
|---|---|
| Deprecation | Tanggal deprecation diumumkan, misalnya @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
Nilai Deprecation mencatat kapan nama lama menjadi deprecated, mengikuti RFC 9745. Nilai ini tidak mengumumkan tanggal penghapusan.
Respons terhadap request yang hanya menggunakan nama terkini tidak membawa kedua header tersebut, jadi kehadiran header itulah sinyalnya: jika Anda tidak pernah melihatnya, tidak ada yang Anda kirim yang dideprekasi.
Tidak ada tanggal penghapusan
Bird tidak mengirim header Sunset karena belum ada tanggal penghapusan. Nama yang digantikan dihapus hanya setelah penggunaannya berhenti. Bird menghubungi pelanggan yang terdampak sebelum penghapusan.
Perlakukan header Deprecation sebagai ajakan untuk bermigrasi sesuai kecepatan Anda sendiri. Header ini tidak memulai hitungan mundur penghapusan.
Request field yang diganti namanya
Nama field yang digantikan berperilaku persis seperti sebelumnya:
- Nama lama tetap diterima pada request, dan tetap menulis nilai yang sama.
- Nama lama tetap dikembalikan pada respons, berdampingan dengan nama penggantinya.
- Nama terkini menang jika Anda mengirim keduanya, sehingga Anda bisa bermigrasi satu call site pada satu waktu tanpa nama lama menimpa nama baru.
Nama field yang diganti dihilangkan dari referensi ini, dan SDK resmi hanya mengekspos nama terkini. Memperbarui SDK Anda dengan demikian memindahkan request ke nama field terkini.
Query parameter yang dideprekasi
Query parameter dideprekasi ketika filter yang lebih baik menggantikannya. Perilakunya berbeda dari field yang diganti namanya dalam tiga hal:
- Tetap dipublikasikan di mana saja. Menghapusnya dari referensi dan SDK akan merusak pemanggil yang sudah mengirimnya, jadi parameter ini tetap ada barisnya di referensi ini, field-nya di setiap SDK, flag-nya di CLI, dan entrinya di skema tool MCP. Memperbarui SDK Anda tidak memigrasikan Anda.
- Tidak ada sisi respons. Query parameter hanya muncul pada request, jadi tidak ada yang berubah di body respons dan tidak ada nama baru untuk dibaca kembali.
- Penggantinya mungkin bukan satu parameter. Filter terkadang digantikan oleh sepasang parameter, jadi deskripsi parameter itu sendiri menyebutkan apa yang harus digunakan sebagai pengganti, bukan menunjuk satu penerus tunggal.
Karena memperbarui SDK tidak memigrasikan Anda, header Deprecation adalah satu-satunya sinyal yang akan Anda terima. Periksa deskripsi parameter di referensi ini: parameter yang dideprekasi dibuka dengan Deprecated: dan menyebutkan penggantinya.
Request body shape yang digantikan
Endpoint pengiriman batch, POST /v1/sms/batches dan POST /v1/email/batches, sebelumnya menerima batch sebagai array JSON top-level tanpa pembungkus. Sekarang endpoint tersebut menerima objek yang array messages-nya berisi item yang sama, yaitu bentuk yang didokumentasikan referensi ini. Request yang body-nya masih berupa array tanpa pembungkus tetap berfungsi persis seperti sebelumnya, dan mendapat header Deprecation. SDK resmi mengirim objek messages, jadi memperbarui SDK Anda memindahkan request ke bentuk terkini.
Migrasi
- Pantau header Deprecation pada respons Anda.
- Temukan request yang menghasilkannya, dan periksa referensi ini untuk operasi terkait guna melihat nama dan bentuk request terkini.
- Pindah ke nama atau bentuk terkini. Kirim hanya bentuk terkini setelah Anda bermigrasi.
Deprecation saat ini
| Operasi | Dideprekasi | Gunakan sebagai pengganti |
|---|---|---|
| WhatsApp: daftar pesan | query parameter phone_number | to atau from |
| SMS dan email: membuat batch pesan | request body bare-array | objek dengan messages |
Tidak ada penggantian nama field yang dideprekasi. Nomor telepon kontak adalah phone_number dan alamat email penerima verifikasi adalah email di dalam to; ejaan lain untuk keduanya ditolak sebagai kesalahan validasi, pada setiap operasi yang menerimanya.
to dan from pada daftar pesan WhatsApp masing-masing mencocokkan satu ujung pesan, dan masing-masing menerima nomor telepon atau user ID berskop bisnis. phone_number mencocokkan kontak di kedua arah, jadi pencarian yang tidak memedulikan arah memerlukan kedua filter, masing-masing satu request.
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integrationPanduan implementasiSend your first email
Dapatkan ringkasan implementasi