Bagaimana seharusnya web API menangani parameter yang salah eja / ekstra?

Pertanyaan: Untuk API web yang menghadap publik (mengirim permintaan Dapatkan / Posting HTTP, dapatkan kembali data JSON / XML), bagaimana seharusnya parameter ditangani yang salah eja atau ekstra.

Sepertinya saya bahwa jika parameter yang salah diabaikan, kesalahan dalam kode pemanggil mungkin tidak diperhatikan karena mereka akan mendapatkan kembali hasil yang valid. Ini mungkin benar terutama dalam situasi di mana itu tidak akan terlihat dengan melihat hasil yang dikembalikan.

Saya mengacu pada parameter opsional saja. Jelas jika parameter yang diperlukan salah eja, maka parameter akan dianggap hilang dan kesalahan akan dikembalikan.

Sebagai contoh , panggilan Place Search API memiliki empat parameter yang diperlukan (lokasi, jari-jari, sensor, dan kunci) dan beberapa parameter opsional (tipe adalah salah satunya).

Saya dapat menjalankan perintah ini (dengan kunci API) dan mendapatkan kembali hasil yang valid:

curl "https://maps.googleapis.com/maps/api/place/search/json?location=45.47554,-122.794189&radius=500&sensor=false&key=<api_key>&type=bakery"

curl "https://maps.googleapis.com/maps/api/place/search/json?location=45.47554,-122.794189&radius=500&sensor=false&key=<api_key>&types=bakery"

Perintah pertama memiliki parameter "types" dalam bentuk singular yang merupakan nama kunci yang tidak valid. API mengabaikan parameter itu dan mengembalikan semua jenis entitas. Dalam hal ini kesalahannya jelas, tetapi mungkin ada waktu (dan panggilan API lainnya) di mana tidak akan terjadi.

Mengabaikan parameter tambahan adalah praktik standar. Sangat mudah untuk menulis kode seperti ini

if (params.type) { 
  ... 
}

Tidak ada masalah dengan memeriksa semua parameter yang diteruskan untuk melihat apakah ada yang tidak valid. Salah eja adalah masalah klien.

Jika itu adalah upaya kecil untuk memasukkan tes kesalahan ejaan untuk nama parameter (berapa banyak pekerjaan yang ingin Anda lakukan, memeriksa nama-nama SEMUA parameter terhadap daftar kesalahan ejaan yang paling mungkin?), Saya mungkin melakukannya tetapi biasanya saya akan sarankan abaikan saja parameter tambahan yang salah eja. Tentu saja, mungkin lebih baik jika WebService mengirim kembali pesan, "Tidak ada parameter yang valid type, maksud Anda types?" tetapi hanya jika Anda memiliki waktu untuk mengimplementasikannya dengan benar, dan karena saya biasanya tidak mengharapkan jenis pesan itu kembali, saya tidak akan melewatkannya jika tidak ada di sana.

Saya pikir itu tergantung pada bagaimana API ditentukan dan siapa yang bertanggung jawab atas masalah ini. Jika saya mendesain API maka saya akan menempatkan kepemilikan untuk memastikan parameter yang benar diharapkan (dan nilai terkait jika ada) ditangani dengan cara yang diharapkan atau jika ada input yang tidak terduga (seperti yang diperlukan untuk melindungi metode dari aneh dan data aneh) maka pengecualian tepat dilempar atau kode kesalahan dikembalikan.

Saya kemudian akan mengatakan bahwa semua input bukan bagian dari daftar parameter yang diharapkan bukan bagian dari masalah API. Itu memungkinkan Anda untuk spesifik dan memiliki spesifikasi yang sangat jelas dan siapa pun yang ingin menggunakan yang bertanggung jawab untuk memastikan mereka menggunakannya dengan benar.

Anda telah menyediakan alat dan serangkaian instruksi tentang cara menggunakannya. Jadikan tanggung jawab pengguna untuk menggunakannya dengan benar.