Menjalankan API, jika saya memperbaiki header tipe konten apakah hal itu akan merusak pelanggan?

Kami menjalankan API dengan beberapa orang menggunakannya. Karena beberapa kecanggungan warisan pada bagian saya, salah satu titik akhir adalah mengembalikan header tipe konten yang salah , jspadahal seharusnya json. Pertanyaan saya adalah, jika kita memperbaikinya dengan bertukar untuk mengembalikan nilai yang benar, seberapa buruk hal itu dapat mengacaukan pelanggan kami yang sudah ada? Atau dengan kata lain, apakah Anda mengharapkan banyak pustaka klien HTTP yang berbeda untuk melakukan kesalahan fatal ketika melihat perubahan seperti itu?

Kami mencoba memutuskan apakah ini adalah perubahan yang dapat kami lakukan tanpa membuat terlalu banyak keringat, atau kami harus hati-hati mengirim email kepada semua pengguna dan mengumumkan periode penghentian bertahun-tahun ... atau sesuatu di antaranya.

Mungkin sedikit tergantung pada apa jenis klien HTTP berbeda yang digunakan, jadi saya melihat agen pengguna. Jawab: banyak yang berbeda! Inilah beberapa yang teratas:

"okhttp / 3.2.0", "python-request / 2.10.0", "Ruby", "python-request / 2.7.0", "Mozilla / 5.0", "Java / 1.8.0_91", "python-request /2.4.3 "," okhttp / 3.3.0 "," Lucee "," Dalvik / 2.1.0 "," Google-HTTP-Java-Client / 1.21.0 "," PHP_appname "," NativeHost "," Java /1.7.0_67 "," Apache-HttpClient / UNAVAILABLE "," Dalvik / 1.6.0 "," Web-sniffer / 1.1.0 "," unirest-objc / 1.1 "

Berbagai pustaka bahasa sisi seluler dan server yang berbeda. Sebagian besar bukan browser yang menjalankan javascript, tetapi beberapa di antaranya juga.

Sebagian besar orang sepertinya tidak menyadari bahwa tipe kontennya salah, tetapi setiap saat permintaan dukungan baru muncul mengeluhkan masalah ini, jadi kami ingin memperbaikinya.

seberapa parah itu bisa mengacaukan segalanya bagi pelanggan kami yang ada?

Itu bisa benar-benar menenggelamkan kapal perang mereka jika mereka telah menulis kode yang bergantung pada Tipe-Konten ini yang salah.

Saya tidak akan mengharapkan pustaka untuk melakukan kesalahan, tetapi saya berharap bahwa dalam beberapa kasus pustaka ketat telah ditimpa perilaku mereka untuk menangani tipe MIME yang salah.

Jika API Anda memiliki nilai versi / revisi di bidang permintaan di suatu tempat, naikkan, dan di versi baru kembalikan jenis yang benar tetapi terus kembalikan jenis yang salah di versi yang lebih lama. Jika Anda tidak memiliki bidang permintaan seperti itu, sekarang adalah waktu yang tepat untuk menambahkannya.

Apakah Anda mengharapkan banyak pustaka klien HTTP untuk membuat kesalahan fatal ketika melihat perubahan seperti itu?

Tidak. Setiap pustaka klien HTTP yang saya kenal akan mengabaikan header tipe konten kecuali programmer secara khusus membaca header itu dan melakukan sesuatu dengannya. Saya bisa membayangkan perpustakaan di mana tipe-konten: application / json secara otomatis menyebabkan parser json untuk terlibat, tetapi saya tidak tahu ada kasus di mana itu benar-benar terjadi.

Sebagian besar orang sepertinya tidak menyadari bahwa tipe kontennya salah, tetapi setiap saat permintaan dukungan baru muncul mengeluhkan masalah ini, jadi kami ingin memperbaikinya.

Bagaimana mereka melihat tajuk yang salah? Mungkin patut untuk dilihat, karena jika header yang salah benar-benar menyebabkan masalah, mereka jelas tidak hanya mengabaikannya, dan mereka mungkin memiliki masalah jika diperbaiki.

Terlalu sulit untuk mengatakan tanpa sign-off dari semua klien Anda. Saya sarankan mengambil salah satu dari dua pendekatan berikut untuk meningkatkan API Anda ke v.Next.

1. Perpanjang API yang ada. Tambahkan string kueri atau variabel lain ke API Anda yang menandakan untuk menggunakan v.Next. Untuk semua permintaan yang menggunakan variabel itu, gunakan tipe konten yang diperbarui.
2. Jalankan instance Staging atau Pra-Produksi API Anda secara paralel dengan API Anda saat ini. Itu harus hampir identik dengan produksi. Bahkan menggunakan back-end yang sama. Meskipun yang satu ini akan memiliki perubahan yang diusulkan untuk v.Next.

Dalam skenario mana pun, komunikasikan kepada klien Anda perubahan yang ingin Anda lakukan dan tanggal / waktu cutover target. Dorong mereka untuk menguji jauh sebelum tanggal target untuk memastikan tidak ada gangguan layanan.

Pastikan Anda memiliki halaman khusus yang merinci perubahan yang dibuat untuk v.Berikutnya. Ini harus dimasukkan dalam komunikasi yang dikirim ke klien Anda. Jika Anda telah membahas segala perbaikan dengan klien yang ada, sertakan yang ada di halaman ini.

Akhirnya, tapak batas antara berkomunikasi berlebihan dengan pelanggan Anda dan mengirim spam kepada mereka. Pemberitahuan ini dapat dengan mudah diabaikan karena prioritas yang lebih mendesak / mendesak muncul.

FWIW, jika semuanya sedang berjalan saya tidak akan terlalu khawatir tentang hal itu. Jika misalnya Anda menemukan bahwa ini menyebabkan kerentanan keamanan yang signifikan maka itu akan menjadi alasan yang bagus untuk mendorong perubahan ini. Kalau tidak, saya akan menunggu sesuatu yang lebih mendesak untuk menyertakan perubahan ini.

Berikut adalah contoh perpustakaan (yah, perintah tunggal) yang akan dipecah:

The PowerShell cmdlet Invoke-RestMethodbertindak berbeda dengan JSON. Jika hasil dari permintaan adalah JSON, XML, atau ATOM / RSS (dan saya pikir itu didasarkan pada header), itu mem-parsing / deserializes dan mengembalikan objek asli, jika tidak mengembalikan data mentah.

Jadi kode yang ada akan ditulis untuk berurusan dengan string (mungkin dengan meneruskannya ConvertFrom-Json), dan tiba-tiba akan gagal.

Saya perhatikan dua konsekuensi:

1. Beberapa perpustakaan klien tidak akan memproses respons dengan benar. Misalnya, respons mengembalikan string alih-alih json atau array.
2. Kompresi tidak selalu diterapkan.