REST API Praktik terbaik: Cara menerima daftar nilai parameter sebagai input [ditutup]

Kami meluncurkan API REST baru dan saya ingin beberapa masukan komunitas tentang praktik terbaik seputar bagaimana kami seharusnya memiliki parameter input yang diformat:

Saat ini, API kami sangat JSON-sentris (hanya mengembalikan JSON). Perdebatan tentang apakah kita ingin / perlu mengembalikan XML adalah masalah yang terpisah.

Karena output API kami adalah JSON centric, kami telah menempuh jalan di mana input kami sedikit JSON centric dan saya telah berpikir bahwa mungkin nyaman untuk beberapa tetapi aneh pada umumnya.

Misalnya, untuk mendapatkan beberapa detail produk di mana beberapa produk dapat ditarik sekaligus saat ini kami miliki:

http://our.api.com/Product?id=["101404","7267261"]

Haruskah kita menyederhanakan ini sebagai:

http://our.api.com/Product?id=101404,7267261

Atau apakah memiliki input JSON berguna? Lebih sakit?

Kami mungkin ingin menerima kedua gaya tetapi apakah fleksibilitas itu sebenarnya menyebabkan lebih banyak kebingungan dan sakit kepala (rawatan, dokumentasi, dll.)?

Kasus yang lebih kompleks adalah ketika kami ingin menawarkan input yang lebih kompleks. Misalnya, jika kami ingin mengizinkan beberapa filter pada pencarian:

http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}

Kami tidak selalu ingin menempatkan jenis filter (mis. Jenis produk dan warna) sebagai nama permintaan seperti ini:

http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]

Karena kami ingin mengelompokkan semua input filter bersama.

Pada akhirnya, apakah ini benar-benar penting? Mungkin ada begitu banyak utiliti JSON di luar sana sehingga tipe input tidak terlalu penting.

Saya tahu klien JavaScript kami yang melakukan panggilan AJAX ke API dapat menghargai input JSON untuk membuat hidup mereka lebih mudah.

A Step Back

Pertama dan terpenting, REST menggambarkan URI sebagai ID unik yang universal. Terlalu banyak orang yang terjebak dalam struktur URI dan URI mana yang lebih "tenang" daripada yang lain. Argumen ini sama menggelikannya dengan mengatakan menamai seseorang "Bob" lebih baik daripada menamainya "Joe" - kedua nama tersebut mendapatkan pekerjaan "mengidentifikasi seseorang". URI tidak lebih dari nama universal yang unik .

Jadi di mata REST berdebat tentang apakah ?id=["101404","7267261"]lebih tenang daripada ?id=101404,7267261atau \Product\101404,7267261agak sia-sia.

Sekarang, setelah mengatakan itu, berkali-kali bagaimana URI dibangun biasanya dapat berfungsi sebagai indikator yang baik untuk masalah lain dalam layanan tenang. Ada beberapa tanda merah di URI Anda dan pertanyaan secara umum.

Saran

1. Beberapa URI untuk sumber daya yang sama dan Content-Location

   Kami mungkin ingin menerima kedua gaya tetapi apakah fleksibilitas itu sebenarnya menyebabkan lebih banyak kebingungan dan sakit kepala (rawatan, dokumentasi, dll.)?

   URI mengidentifikasi sumber daya. Setiap sumber daya harus memiliki satu URI kanonik. Ini tidak berarti bahwa Anda tidak dapat memiliki dua URI menunjuk ke sumber daya yang sama tetapi ada cara yang jelas untuk melakukannya. Jika Anda memutuskan untuk menggunakan JSON dan format berbasis daftar (atau format lainnya), Anda perlu memutuskan format mana yang merupakan URI kanonis utama . Semua respons terhadap URI lain yang menunjuk ke "sumber daya" yang sama harus mencakup Content-Locationheader .

   Menempel dengan analogi nama, memiliki beberapa URI seperti memiliki nama panggilan untuk orang-orang. Ini sangat bisa diterima dan sering kali sangat berguna, namun jika saya menggunakan nama panggilan saya mungkin masih ingin tahu nama lengkap mereka - cara "resmi" untuk merujuk orang itu. Dengan cara ini ketika seseorang menyebut seseorang dengan nama lengkapnya, "Nichloas Telsa", saya tahu mereka berbicara tentang orang yang sama yang saya sebut sebagai "Nick".

2. "Cari" di URI Anda

   Kasus yang lebih kompleks adalah ketika kami ingin menawarkan input yang lebih kompleks. Misalnya, jika kami ingin mengizinkan beberapa filter pada pencarian ...

   Aturan umum saya adalah, jika URI Anda mengandung kata kerja, itu mungkin merupakan indikasi bahwa ada sesuatu yang tidak aktif. URI mengidentifikasi sumber daya, namun mereka tidak boleh menunjukkan apa yang kami lakukan terhadap sumber daya itu. Itu pekerjaan HTTP atau dalam istilah yang tenang, "antarmuka seragam" kami.

   Untuk mengalahkan analogi nama mati, menggunakan kata kerja dalam URI seperti mengubah nama seseorang ketika Anda ingin berinteraksi dengan mereka. Jika saya berinteraksi dengan Bob, nama Bob tidak menjadi "BobHi" ketika saya ingin mengatakan Hai padanya. Demikian pula, ketika kita ingin "mencari" Produk, struktur URI kita seharusnya tidak berubah dari "/ Produk / ..." menjadi "/ Pencarian / ...".

Menjawab Pertanyaan Awal Anda

1. Mengenai ["101404","7267261"]vs 101404,7267261: Saran saya di sini adalah untuk menghindari sintaks JSON demi kesederhanaan (yaitu tidak mengharuskan pengguna Anda melakukan pengkodean URL ketika Anda tidak benar-benar harus). Ini akan membuat API Anda sedikit lebih bermanfaat. Lebih baik lagi, seperti yang direkomendasikan orang lain, gunakan application/x-www-form-urlencodedformat standar karena mungkin paling akrab bagi pengguna akhir Anda (mis ?id[]=101404&id[]=7267261.). Itu mungkin tidak "cantik", tetapi Pretty URI tidak perlu berarti URI yang Dapat Digunakan. Namun, untuk menegaskan kembali poin awal saya, pada akhirnya ketika berbicara tentang REST, tidak masalah. Jangan terlalu memikirkannya.

2. Contoh URI pencarian kompleks Anda dapat diselesaikan dengan cara yang hampir sama dengan contoh produk Anda. Saya akan merekomendasikan application/x-www-form-urlencodedformat lagi karena sudah standar yang banyak akrab. Juga, saya akan merekomendasikan menggabungkan keduanya.

URI Anda ...

/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}    

URI Anda setelah dikodekan dengan URI ...

/Search?term=pumas&filters=%7B%22productType%22%3A%5B%22Clothing%22%2C%22Bags%22%5D%2C%22color%22%3A%5B%22Black%22%2C%22Red%22%5D%7D

Dapat diubah menjadi ...

/Product?term=pumas&productType[]=Clothing&productType[]=Bags&color[]=Black&color[]=Red

Selain menghindari persyaratan pengkodean URL dan membuat hal-hal terlihat sedikit lebih standar, sekarang sedikit menyeragamkan API. Pengguna tahu bahwa jika mereka ingin mengambil Produk atau Daftar Produk (keduanya dianggap sebagai "sumber daya" tunggal dalam istilah RESTful), mereka tertarik pada /Product/...URI.

Cara standar untuk meneruskan daftar nilai sebagai parameter URL adalah mengulanginya:

http://our.api.com/Product?id=101404&id=7267261

Sebagian besar kode server akan menafsirkan ini sebagai daftar nilai, meskipun banyak yang memiliki penyederhanaan nilai tunggal sehingga Anda mungkin harus mencari.

Nilai yang dibatasi juga oke.

Jika Anda perlu mengirim JSON ke server, saya tidak suka melihatnya di URL (yang merupakan format berbeda). Secara khusus, URL memiliki batasan ukuran (dalam praktiknya jika tidak secara teori).

Cara saya melihat beberapa melakukan kueri yang rumit RESTfully adalah dalam dua langkah:

1. POST persyaratan kueri Anda, menerima kembali ID (dasarnya membuat sumber daya kriteria pencarian)
2. GET pencarian, referensi ID di atas
3. secara opsional HAPUS persyaratan permintaan jika perlu, tetapi perhatikan bahwa persyaratan itu tersedia untuk digunakan kembali.

Pertama:

Saya pikir Anda bisa melakukannya dengan 2 cara

http://our.api.com/Product/<id> : jika Anda hanya ingin satu catatan

http://our.api.com/Product : jika Anda ingin semua catatan

http://our.api.com/Product/<id1>,<id2> : seperti yang disarankan James dapat menjadi pilihan karena apa yang muncul setelah tag Produk adalah parameter

Atau yang paling saya sukai adalah:

Anda dapat menggunakan properti Hypermedia sebagai mesin status aplikasi (HATEOAS) dari RestFul WS dan melakukan panggilan http://our.api.com/Productyang akan mengembalikan URL setara http://our.api.com/Product/<id>dan memanggil mereka setelah ini.

Kedua

Ketika Anda harus melakukan pertanyaan pada panggilan url. Saya akan menyarankan menggunakan HATEOAS lagi.

1) Lakukan panggilan masuk ke http://our.api.com/term/pumas/productType/clothing/color/black

2) Lakukan panggilan masuk ke http://our.api.com/term/pumas/productType/clothing,bags/color/black,red

3) (Menggunakan HATEOAS) Lakukan panggilan ke ` http://our.api.com/term/pumas/productType/ -> terima url semua pakaian yang memungkinkan url -> panggil yang Anda inginkan (pakaian dan tas) - > terima kemungkinan url warna -> panggil yang Anda inginkan

Anda mungkin ingin memeriksa RFC 6570 . Spesifikasi Templat URI ini menunjukkan banyak contoh bagaimana URL dapat berisi parameter.

Kasus pertama:

Pencarian produk normal akan terlihat seperti ini

http://our.api.com/product/1

Jadi saya berpikir bahwa praktik terbaik adalah bagi Anda untuk melakukan ini

http://our.api.com/Product/101404,7267261

Kasus kedua

Cari dengan parameter querystring - baik seperti ini. Saya akan tergoda untuk menggabungkan istilah dengan AND dan OR daripada menggunakan[] .

PS Ini bisa subjektif, jadi lakukan apa yang menurut Anda nyaman.

Alasan untuk menempatkan data di url adalah agar tautan dapat ditempel di situs / dibagi di antara pengguna. Jika ini bukan masalah, gunakan JSON / POST.

EDIT: Pada refleksi saya pikir pendekatan ini sesuai dengan suatu entitas dengan kunci majemuk, tetapi bukan permintaan untuk banyak entitas.

Saya akan memihak jawaban nategood karena sudah lengkap dan sepertinya sudah menyenangkan kebutuhan Anda. Meskipun demikian, saya ingin menambahkan komentar tentang mengidentifikasi beberapa (1 atau lebih) sumber daya dengan cara itu:

http://our.api.com/Product/101404,7267261

Dengan demikian, Anda:

Komplekskan klien dengan memaksa mereka untuk menafsirkan respons Anda sebagai array, yang bagi saya kontra intuitif jika saya membuat permintaan berikut:http://our.api.com/Product/101404

Buat redundant APIs dengan satu API untuk mendapatkan semua produk dan yang di atas untuk mendapatkan 1 atau banyak. Karena Anda tidak boleh menampilkan lebih dari 1 halaman detail kepada pengguna demi UX, saya yakin memiliki lebih dari 1 ID akan sia-sia dan murni digunakan untuk memfilter produk.

Mungkin tidak bermasalah, tetapi Anda harus menangani sendiri sisi server ini dengan mengembalikan satu entitas (dengan memverifikasi apakah respons Anda mengandung satu atau lebih) atau membiarkan klien mengelolanya.

Contoh

Saya ingin memesan buku dari Amazing . Saya tahu persis buku mana itu dan saya melihatnya di daftar ketika menavigasi untuk buku-buku Horor:

1. 10 000 garis luar biasa, 0 tes luar biasa
2. Kembalinya monster yang menakjubkan
3. Mari kita duplikat kode yang luar biasa
4. Awal yang menakjubkan dari akhir

Setelah memilih buku kedua, saya diarahkan ke halaman yang merinci bagian buku dari daftar:

--------------------------------------------
Book #1
--------------------------------------------
    Title: The return of the amazing monster
    Summary:
    Pages:
    Publisher:
--------------------------------------------

Atau di halaman memberi saya rincian lengkap dari buku itu saja?

---------------------------------
The return of the amazing monster
---------------------------------
Summary:
Pages:
Publisher:
---------------------------------

Pendapat saya

Saya akan menyarankan menggunakan ID dalam variabel path ketika unicity dijamin ketika mendapatkan rincian sumber daya ini. Misalnya, API di bawah ini menyarankan beberapa cara untuk mendapatkan detail untuk sumber daya tertentu (dengan asumsi produk memiliki ID unik dan spesifikasi untuk produk tersebut memiliki nama unik dan Anda dapat menavigasi dari atas ke bawah):

/products/{id}
/products/{id}/specs/{name}

Saat Anda membutuhkan lebih dari 1 sumber daya, saya sarankan memfilter dari koleksi yang lebih besar. Untuk contoh yang sama:

/products?ids=

Tentu saja, ini pendapat saya karena tidak dipaksakan.