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

126

REST API dapat memiliki argumen di beberapa tempat:

Dalam isi permintaan - Sebagai bagian dari badan json, atau jenis MIME lainnya
Dalam string kueri - mis/api/resource?p1=v1&p2=v2
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 .

— Jonathan
sumber

Apakah ini menjawab pertanyaan Anda? Praktik terbaik REST API: Di mana harus meletakkan parameter?

— Steve Chambers

Selain hal di atas, bagaimana jika menggunakan header?

— variabel

Jawaban:

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.

— stan0
sumber

Pengambilan yang masuk akal untuk analisis Anda di atas adalah bahwa operasi idempoten paling baik disimpan dalam string kueri url dan CRUD paling baik disimpan untuk badan respons yang diketik secara ketat, yang pada dasarnya memanfaatkan SOP dan mencegah bentuk yang sangat dasar dari serangan rekayasa sosial / phishing

— Rice

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.

— Leonel Galán
sumber

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.

— Jonathan
sumber

Memilih cara menyusun API Anda berdasarkan kenyamanan pengembangan bukanlah praktik yang baik.

— Eric Stein

Seperti yang dikatakan @EricStein, Anda mendapatkannya terbalik.

— DanMan

Teman-teman, alasan saya menanyakan pertanyaan ini adalah untuk mendapatkan jawaban yang benar. Silakan, tulis jawaban dan saya akan menghapus salah saya. @EnakBarokah

— Jonathan

@Jonathan apis yang mudah dikonsumsi melalui tangan manusia hampir selalu merupakan apis yang baik. Kudos karena secara akurat memanggil KISS

— Chris Marisic

@AkshayHiremath Dia mengacu pada fakta bahwa Anda mungkin mengirim sesuatu yang lain di badan, misalnya jika Anda mengirim header ContentType seperti "image / jpeg" Anda harus memiliki badan pesan Anda berisi data jpeg dan tidak dapat menyertakan apa pun di itu

— Shayaan