Versi dan kompatibilitas

API memiliki satu versi mayor, /v1, dan versi itu hanya bertambah. Integrasi yang ditulis hari ini tetap berfungsi saat fitur baru hadir: tidak ada yang diandalkannya yang diganti namanya, dihapus, atau diberi arti baru.

Nomor versi

API memiliki nomor versi seperti 1.62.0. Nomor ini berubah pada setiap rilis:

• nomor minor saat ada yang ditambahkan: endpoint, field, peristiwa;
• nomor patch saat deskripsi atau teks pesan diperbaiki dan tidak ada hal lain yang berubah.

Anda dapat membaca versi yang dilayani sebuah alamat kapan saja:

GET /v1/health juga memiliki version, tetapi itu adalah versi rilis Sursa yang melayani alamat tersebut, bukan versi API.

Anda tidak memilih versi minor: setiap permintaan dilayani oleh versi saat ini. Berkat aturan di bawah, hal itu aman.

Apa yang dapat berubah di /v1

Perubahan berikut dapat hadir di versi minor mana pun. Tulis integrasi Anda sehingga perubahan itu tidak merusaknya:

• Endpoint baru.
• Parameter dan field permintaan baru yang opsional. Permintaan tanpa parameter atau field itu berperilaku seperti sebelumnya.
• Field baru dalam respons, objek, dan peristiwa.
• Nilai enum baru dalam respons, seperti status kartu baru atau jenis peristiwa baru.
• Kode error baru, dan header respons baru.
• Batas yang menjadi kurang ketat: panjang maksimum yang lebih panjang, rentang yang lebih lebar.
• Teks message error dan deskripsi yang susunan katanya diubah.

Apa yang harus dapat ditoleransi kode Anda

• Abaikan field yang tidak Anda kenal. Jangan gagal ketika respons memiliki lebih banyak field daripada yang Anda harapkan, dan jangan memakai skema ketat yang menolaknya.
• Terima nilai enum yang tidak Anda kenal. Setiap enum dalam respons dapat bertambah. Perlakukan nilai yang tidak dikenal sebagai “lainnya”, bukan sebagai error.
• Lewati jenis peristiwa yang tidak Anda kenal, baik di webhook maupun di stream.
• Tangani kode error yang tidak dikenal menurut status HTTP-nya: lihat Error.
• Jangan bergantung pada urutan field dalam objek JSON, atau pada teks pesan yang persis.

Apa yang tidak pernah berubah di /v1

• Path, parameter, field, atau nilai enum tidak pernah diganti namanya atau dihapus.
• Tipe field tidak pernah berubah, dan field tidak pernah mendapat arti baru, seperti satuan baru.
• Permintaan yang diterima hari ini tidak akan ditolak nanti.
• Kode status respons yang berhasil tetap sama.
• Kode error mempertahankan artinya, dan field detail dalam respons error mempertahankan bentuknya.
• Jenis peristiwa tidak pernah diganti namanya atau dihapus, dan data miliknya hanya mendapat field tambahan.

Perubahan yang merusak kompatibilitas

Jika suatu saat diperlukan perubahan yang tidak kompatibel, perubahan itu dirilis sebagai versi mayor baru, seperti /v2, di samping /v1. /v1 tetap berfungsi tanpa perubahan, dan keduanya berjalan berdampingan.

Saat sebuah rute akan dihentikan:

1. Rute itu ditandai deprecated dalam spesifikasi dan dicantumkan di log perubahan beserta tanggal rute itu akan dimatikan.
2. Responsnya membawa header Deprecation: true dan Sunset: <date>.
3. Rute itu tetap berfungsi setidaknya 180 hari setelah pengumuman. Organisasi yang kunci API-nya memakai rute itu diberi tahu secara tertulis setidaknya 90 hari sebelumnya.
4. Setelah tanggal penghentian, rute itu menjawab 410 dengan kode api.gone selama 90 hari berikutnya.

Perhatikan header Deprecation di log atau pemantauan Anda: header itu adalah tanda paling awal bahwa rute yang Anda pakai akan dihapus.

Tetap mendapat informasi

Log perubahan di portal ini mencantumkan setiap rilis beserta apa yang ditambahkan dan apa yang dinyatakan usang. Sebelum Anda memperbarui integrasi Anda sendiri, bandingkan kodenya dengan entri sejak versi yang menjadi dasar pembuatannya.