Kebijakan untuk penyusun Api Data

Serangkaian kebijakan mengatur penyusun Api Data yang terkait dengan perubahan, pemberitahuan, rilis, dan penerapan versi yang melanggar.

Penerapan versi dan rilis

Rilis dalam konteks penyusun Api Data mengacu pada setiap versi perangkat lunak yang diterbitkan, yang diidentifikasi dengan Major.Minor.Patch format . Rilis ini termasuk dalam tiga kategori: stabil, melanggar perubahan, dan pratinjau.

Rilis yang stabil

Versi stabil penyusun Api Data kompatibel dengan versi terdahulu. Kompatibel mundur menyiratkan bahwa kode apa pun yang Anda tulis yang bergantung pada satu versi pembuat Api Data dapat mengadopsi versi stabil yang lebih baru tanpa memerlukan perubahan kode apa pun untuk mempertahankan kebenaran atau fungsionalitas yang ada.

Melanggar rilis perubahan

Versi perubahan yang melanggar penyusun Api Data tidak kompatibel dengan versi terdahulu. Mengadopsi versi perubahan yang melanggar dalam kode klien yang ada mungkin memerlukan perubahan kode untuk memastikan klien bertindak persis seperti saat menargetkan versi sebelumnya.

Versi perubahan yang melanggar diumumkan melalui artikel daftar perubahan yang melanggar dan dalam deskripsi perubahan rilis GitHub. Publikasi versi pratinjau/rilis kandidat mendahului melanggar versi perubahan kecuali perubahan memperbaiki masalah keamanan, privasi, atau hukum penting. Meskipun versi penyusun Api Data sebelumnya mungkin tetap tersedia di halaman rilis GitHub, kami sarankan Anda meningkatkan ke rilis terbaru, yang mungkin menyertakan perbaikan bug.

Rilis pratinjau

Rilis pratinjau penyusun API Data diidentifikasi dengan X.Y.Z-rc skema penerapan versi. Akhiran -rc menunjukkan bahwa build adalah "kandidat rilis." Rilis pratinjau digunakan untuk mengumpulkan umpan balik tentang fitur baru dan perubahan lainnya.

Kecuali kami berencana untuk secara sengaja membuat perubahan signifikan dari versi stabil terakhir, kami menerbitkan versi pratinjau berikutnya dengan semuanya dari rilis stabil terbaru dan fitur pratinjau baru. Pembaruan penyusun Api Data berikutnya mungkin merusak beberapa fitur pratinjau baru yang kami tambahkan di antara versi pratinjau. Perilaku melanggar ini berarti Anda mungkin perlu mengubah kode Anda untuk membuat semuanya berfungsi lagi.

Versi pratinjau tidak dimaksudkan untuk penggunaan jangka panjang atau produksi. Saat versi stabil atau pratinjau baru tersedia, versi pratinjau yang lebih lama mungkin tidak dapat diakses lagi. Yang terbaik adalah menggunakan versi pratinjau hanya saat Anda secara aktif mengerjakan fitur baru dan siap untuk beralih ke versi non-pratinjau segera setelah rilis. Jika beberapa fitur dari versi pratinjau disertakan dalam versi stabil baru, fitur pratinjau yang tersisa ditambahkan ke versi pratinjau baru untuk Anda coba.

Tabel perubahan versi

Memecahkan Perubahan

Untuk memprioritaskan keamanan, meningkatkan fitur, dan mempertahankan kualitas kode, versi baru perangkat lunak kami mungkin termasuk perubahan yang melanggar. Meskipun kami berusaha untuk meminimalkan perubahan ini melalui pilihan arsitektur yang cermat, perubahan tersebut masih dapat terjadi. Dalam kasus seperti itu, kami menjadikannya prioritas untuk mengumumkannya dan memberikan solusi yang mungkin.

Apa itu perubahan yang melanggar?

Perubahan yang melanggar adalah modifikasi yang mengharuskan Anda memperbarui aplikasi untuk mencegah gangguan. Dalam penyusun Api Data, perubahan yang melanggar dapat mencakup perubahan pada kontrak REST API, pembuatan skema GraphQL, dan elemen lain yang memengaruhi kompatibilitas dan fungsionalitas.

Contoh perubahan yang melanggar

Contoh berikut adalah daftar perubahan mencolok yang tidak ada pada penyusun Api Data:

• Modifikasi kontrak REST API
• Perubahan dalam pembuatan skema GraphQL
• Perubahan yang memengaruhi kompatibilitas mundur
• Penghapusan atau penggantian nama API atau parameter
• Perubahan kode kesalahan
• Penyesuaian fungsionalitas definisi izin
• Penghapusan parameter, bidang permintaan, atau bidang respons yang diizinkan
• Penambahan parameter wajib atau bidang permintaan tanpa nilai default
• Modifikasi pada fungsionalitas titik akhir API yang dimaksudkan

Definisi perubahan yang tidak terganggu

Perubahan yang tidak melanggar mengacu pada perubahan yang dapat diintegrasikan ke dalam aplikasi Anda tanpa menyebabkan gangguan. Perubahan non-pemisah biasanya dikomunikasikan setelah implementasi. Aplikasi Anda harus dirancang untuk menangani perubahan ini tanpa pemberitahuan sebelumnya.

Contoh Perubahan Yang Tidak Melanggar

Contoh berikut adalah daftar yang tidak ada perubahan yang tidak terpecat pada penyusun Api Data:

• Pengenalan titik akhir baru
• Penambahan metode ke titik akhir yang ada
• Penggabungan bidang baru dalam respons dan permintaan
• Penyesuaian urutan bidang dalam respons
• Pengenalan header permintaan opsional
• Perubahan pada panjang dan ukuran respons data
• Perubahan pada pesan dan kode kesalahan
• Perbaikan untuk kode respons HTTP
• Metadata tambahan dalam dokumen OpenAPI yang dihasilkan

Bagaimana cara mengomunikasikan perubahan yang melanggar?

Kami menjadikannya prioritas untuk segera memberi tahu Anda tentang melanggar perubahan. Anda dapat menemukan pemberitahuan perubahan mencolok dalam catatan rilis rilis pembuat Api Data di GitHub, dan di artikel daftar perubahan pemecahan khusus.

Daftar perubahan pemisah saat ini

Perubahan yang melanggar dan penghentian fitur diumumkan dalam artikel ini.

• Sampai sekarang, tidak ada perubahan yang melanggar

Konten terkait

• Apa yang baru
• Fitur khusus database