Praktik terbaik REST API: args dalam string kueri vs dalam isi permintaan

REST API dapat memiliki argumen di beberapa tempat:

1. Dalam isi permintaan - Sebagai bagian dari badan json, atau jenis MIME lainnya
2. Dalam string kueri - mis/api/resource?p1=v1&p2=v2
3. Sebagai bagian dari jalur URL - mis/api/resource/v1/v2

Apa praktik terbaik dan pertimbangan memilih antara 1 dan 2 di atas?
2 vs 3 dibahas di sini .

Apa praktik terbaik dan pertimbangan memilih antara 1 dan 2 di atas?

Biasanya badan konten digunakan untuk data yang akan diunggah / diunduh ke / dari server dan parameter kueri digunakan untuk menentukan data persis yang diminta. Misalnya saat Anda mengupload file, Anda menentukan nama, jenis mime, dll. Di body tetapi ketika Anda mengambil daftar file, Anda dapat menggunakan parameter kueri untuk memfilter daftar berdasarkan beberapa properti file. Secara umum, parameter kueri adalah properti kueri, bukan datanya.

Tentu saja ini bukan aturan yang ketat - Anda dapat menerapkannya dengan cara apa pun yang menurut Anda lebih sesuai / sesuai untuk Anda.

Anda mungkin juga ingin memeriksa artikel wikipedia tentang string kueri , terutama dua paragraf pertama.

Saya akan menganggap Anda berbicara tentang permintaan POST / PUT. Secara semantik badan permintaan harus berisi data yang Anda posting atau tambal.

String kueri, sebagai bagian dari URL (URI), ada di sana untuk mengidentifikasi sumber daya mana yang Anda posting atau tambal.

Anda meminta praktik terbaik, semantik berikut adalah milik saya. Tentu saja menggunakan aturan praktis Anda harus bekerja, terutama jika kerangka web Anda menggunakan abstrak ini menjadi parameter .

Yang paling Anda ketahui:

• Beberapa server web memiliki batasan panjang URI.
• Anda dapat mengirim parameter di dalam tubuh permintaan dengan CURL.
• Kemana Anda mengirim data seharusnya tidak berpengaruh pada debugging.

Berikut ini adalah aturan praktis saya ...

Kapan menggunakan tubuh:

• Jika argumen tidak memiliki kunci datar: struktur nilai
• Jika nilai tidak dapat dibaca manusia, seperti data biner serial
• Jika Anda memiliki banyak argumen

Kapan menggunakan string kueri:

• Ketika argumen sedemikian rupa sehingga Anda ingin melihatnya saat debugging
• Ketika Anda ingin dapat memanggil mereka secara manual sambil mengembangkan kode misalnya dengan curl
• Ketika argumen umum terjadi di banyak layanan web
• Saat Anda sudah mengirim tipe konten yang berbeda seperti application/octet-stream

Perhatikan bahwa Anda dapat mencampur dan mencocokkan - letakkan yang umum, yang harus dapat di-debug dalam string kueri, dan letakkan sisanya di json.