Konsep REST API

Saya memiliki tiga pertanyaan tentang desain REST API yang saya harap seseorang dapat menjelaskan. Saya telah mencari tanpa henti selama berjam-jam tetapi belum menemukan jawaban untuk pertanyaan saya di mana saja (mungkin saya tidak tahu harus mencari apa?).

pertanyaan 1

Pertanyaan pertama saya berkaitan dengan tindakan / RPC. Saya telah mengembangkan REST API untuk sementara waktu dan saya terbiasa memikirkan hal-hal dalam hal pengumpulan dan sumber daya. Namun, saya telah menemukan beberapa kasus di mana paradigma tersebut tampaknya tidak berlaku dan saya bertanya-tanya apakah ada cara untuk mendamaikan ini dengan paradigma REST.

Secara khusus, saya memiliki kasus di mana memodifikasi sumber daya menyebabkan email dihasilkan. Namun, pada titik selanjutnya pengguna dapat secara khusus menunjukkan bahwa mereka ingin mengirim ulang email yang dikirim sebelumnya. Saat mengirim ulang email, tidak ada sumber daya yang dimodifikasi. Tidak ada kondisi yang diubah. Itu hanya tindakan yang perlu terjadi. Tindakan ini terkait dengan jenis sumber daya tertentu.

Apakah pantas mencampurkan semacam aksi panggilan dengan URI sumber daya (mis. /collection/123?action=resendEmail)? Apakah lebih baik untuk menentukan tindakan dan meneruskan id sumber daya ke sana (mis. /collection/resendEmail?id=123)? Apakah ini cara yang salah untuk melakukannya? Secara tradisional (setidaknya dengan HTTP) tindakan yang dilakukan adalah metode permintaan (GET, POST, PUT, DELETE), tetapi tindakan tersebut tidak benar-benar memungkinkan tindakan khusus dengan sumber daya.

Pertanyaan 2

Saya menggunakan bagian querystring dari URL untuk memfilter set sumber daya yang dikembalikan ketika meminta koleksi (misalnya /collection?someField=someval). Di dalam kontroler API saya, saya kemudian menentukan perbandingan apa yang akan dilakukan dengan bidang dan nilai tersebut. Saya menemukan ini benar-benar tidak berhasil. Saya perlu cara untuk memungkinkan pengguna API menentukan jenis perbandingan yang ingin mereka lakukan.

Ide terbaik saya sudah datang dengan sejauh ini adalah untuk memungkinkan pengguna API untuk menentukan itu sebagai tambahan untuk nama field (misalnya /collection?someField:gte=someval- untuk menunjukkan bahwa itu harus kembali sumber mana someFieldlebih besar dari atau sama dengan (> =) apa pun somevaladalah Apakah ini ide yang baik? Ide yang buruk? Jika demikian, mengapa? Apakah ada cara yang lebih baik untuk memungkinkan pengguna menentukan jenis perbandingan untuk melakukan dengan bidang dan nilai yang diberikan?

Pertanyaan 3

Saya sering melihat URI yang terlihat seperti /person/123/dogsmendapatkan persons dogs. Saya biasanya menghindari sesuatu seperti itu karena pada akhirnya saya menemukan bahwa dengan membuat URI seperti itu Anda sebenarnya hanya mengakses dogskoleksi yang difilter oleh personID tertentu . Itu akan setara dengan /dogs?person=123. Apakah benar-benar ada alasan bagus untuk REST URI lebih dari dua level ( /collection/resource_id)?

Apakah pantas mencampurkan semacam aksi panggilan dengan URI sumber daya (mis. /collection/123?action=resendEmail)? Apakah lebih baik untuk menentukan tindakan dan meneruskan id sumber daya ke sana (mis. /collection/resendEmail?id=123)? Apakah ini cara yang salah untuk melakukannya? Secara tradisional (setidaknya dengan HTTP) tindakan yang dilakukan adalah metode permintaan (GET, POST, PUT, DELETE), tetapi tindakan tersebut tidak benar-benar memungkinkan tindakan khusus dengan sumber daya.

Saya lebih suka memodelkannya dengan cara yang berbeda, dengan koleksi sumber daya yang mewakili email yang akan dikirim; pengiriman akan diproses oleh internal layanan pada waktunya, pada titik mana sumber daya yang sesuai akan dihapus. (Atau pengguna dapat HAPUS sumber daya lebih awal, menyebabkan pembatalan permintaan untuk melakukan pengiriman.)

Apa pun yang Anda lakukan, jangan letakkan kata kerja di nama sumber daya! Itu kata benda (dan bagian permintaan adalah himpunan kata sifat). Kata kerja nomina weirds REST!

Saya menggunakan bagian querystring dari URL untuk memfilter set sumber daya yang dikembalikan ketika meminta koleksi (misalnya /collection?someField=someval). Di dalam kontroler API saya, saya kemudian menentukan perbandingan apa yang akan dilakukan dengan bidang dan nilai tersebut. Saya menemukan ini benar-benar tidak berhasil. Saya perlu cara untuk memungkinkan pengguna API menentukan jenis perbandingan yang ingin mereka lakukan.

Ide terbaik yang saya buat sejauh ini adalah mengizinkan pengguna API untuk menentukannya sebagai tambahan untuk nama bidang (misalnya /collection?someField:gte=someval- untuk menunjukkan bahwa ia harus mengembalikan sumber daya di mana someField lebih besar dari atau sama dengan ( >=) apa pun somevalitu. Apakah ini ide yang baik? Ide yang buruk? Jika demikian, mengapa? Apakah ada cara yang lebih baik untuk memungkinkan pengguna menentukan jenis perbandingan untuk melakukan dengan bidang dan nilai yang diberikan?

Saya lebih suka menentukan klausa filter umum dan menjadikannya sebagai parameter kueri opsional pada setiap permintaan untuk mengambil konten koleksi. Klien kemudian dapat menentukan dengan tepat bagaimana membatasi set yang dikembalikan, dengan cara apa pun yang Anda inginkan. Saya juga sedikit khawatir tentang kemampuan menemukan bahasa filter / query; semakin kaya Anda membuatnya, semakin sulit bagi klien sewenang-wenang untuk menemukannya. Pendekatan alternatif yang, paling tidak secara teoritis, berkaitan dengan masalah keterjangkauan adalah untuk memungkinkan membuat sub-sumber daya pembatasan koleksi, yang diperoleh klien dengan POST dokumen yang menjelaskan pembatasan sumber daya pengumpulan. Ini masih sedikit pelecehan, tetapi setidaknya itu adalah salah satu yang Anda dapat dengan mudah ditemukan!

Jenis penemuan ini adalah salah satu hal yang menurut saya paling tidak kuat dengan REST.

Saya sering melihat URI yang terlihat seperti /person/123/dogsmendapatkan anjing orang. Saya biasanya menghindari sesuatu seperti itu karena pada akhirnya saya menemukan bahwa dengan membuat URI seperti itu Anda sebenarnya hanya mengakses koleksi anjing yang difilter oleh ID orang tertentu. Itu akan setara dengan /dogs?person=123. Apakah benar-benar ada alasan bagus untuk REST URI lebih dari dua level ( /collection/resource_id)?

Ketika koleksi bersarang benar-benar merupakan sub-fitur dari entitas anggota koleksi luar, masuk akal untuk menyusunnya sebagai sub-sumber daya. Yang dimaksud dengan "sub-fitur" yang saya maksud adalah hubungan komposisi UML, di mana penghancuran sumber daya luar secara alami berarti penghancuran koleksi dalam.

Jenis koleksi lainnya dapat dimodelkan sebagai pengalihan HTTP; dengan demikian /person/123/dogsmemang dapat ditanggapi dengan melakukan 307 yang dialihkan ke /dogs?person=123. Dalam hal ini, koleksi sebenarnya bukan komposisi UML, melainkan agregasi UML. Perbedaan itu penting; ini penting!

Dapat dimengerti untuk sedikit bingung tentang cara menggunakan REST dengan benar berdasarkan semua cara yang saya lihat perusahaan besar merancang API REST mereka.

Anda benar karena REST adalah sistem Pengumpulan Sumber Daya. Itu singkatan dari Representational State Transfer. Bukan definisi yang bagus jika Anda bertanya kepada saya. Tetapi konsep utamanya adalah 4 HTTP VERBs dan tidak bernegara.

Bagian penting yang perlu diperhatikan adalah bahwa Anda hanya memiliki 4 KATA KERJA dengan REST. Ini adalah GET, POST, PUT dan DELETE. resendContoh Anda akan menambahkan kata kerja baru ke REST. Ini harus menjadi bendera merah.

pertanyaan 1

Penting untuk menyadari bahwa penelepon REST API Anda tidak perlu tahu bahwa melakukan PUTkoleksi Anda akan menghasilkan email yang dihasilkan. Baunya bocor bagiku. Apa yang bisa mereka ketahui adalah bahwa melakukan PUTdapat menghasilkan tugas tambahan yang bisa mereka tanyakan nanti. Mereka akan mengetahui hal ini dengan melakukan GETpada sumber daya yang baru dibuat. Itu GETakan mengembalikan sumber daya dan semua Taskid sumber daya yang terkait dengannya. Anda kemudian dapat meminta tugas-tugas itu untuk menentukan status mereka dan bahkan mengirimkan yang baru Task.

Anda punya beberapa pilihan.

REST - Pendekatan berbasis sumber daya tugas

Buat taskssumber daya di mana Anda bisa mengirimkan tugas spesifik ke sistem Anda untuk melakukan tindakan. Anda kemudian dapat GETtugas berdasarkan IDitu dikembalikan untuk menentukan statusnya.

Atau Anda dapat mencampur dalam SOAP over HTTPLayanan Web untuk menambahkan beberapa RPC ke arsitektur Anda.

meminta semua tugas untuk sumber daya tertentu

GET http://server/api/myCollection/123/tasks

{ "tasks" :
    [ { "22333" : "http://server/api/tasks/223333" } ] 
}

contoh sumber daya tugas

PUT http://server/api/tasks

{ 
    "type" : "send-email" , 
    "parameters" : 
    { 
         "collection-type" : "foo" , 
         "collection-id" : "123" 
    } 
}

==> mengembalikan id tugas

223334

GET http://server/api/tasks/223334

{ 
    "status" : "complete" , 
    "date" : "whenever" 
}

REST- Menggunakan POST untuk memicu tindakan

Anda selalu dapat POSTmenambahkan data ke sumber daya. Menurut pendapat saya ini akan melanggar semangat REST tetapi masih sesuai.

Anda dapat melakukan POST yang mirip dengan ini:

POST http://server/api/collection/123

{ "action" : "send-email" }

Anda akan memperbarui sumber daya 123 dari pengumpulan dengan data tambahan. Data tambahan itu pada dasarnya adalah tindakan yang memberi tahu backend untuk mengirim email untuk sumber itu.

Masalah yang saya miliki dengan ini adalah bahwa GETpada sumber daya akan mengembalikan data yang diperbarui ini. Namun, ini akan menyelesaikan kebutuhan Anda dan masih TETAP.

SOAP - Layanan Web yang menerima sumber daya yang diperoleh dari REST

Buat WebService baru di mana Anda dapat mengirim email berdasarkan ID sumber daya sebelumnya dari REST API. Saya tidak akan membahas detail tentang SOAP di sini karena pertanyaan awalnya adalah tentang REST dan dua konsep / teknologi ini tidak boleh dibandingkan karena ini adalah Apel dan Jeruk .

Pertanyaan 2

Anda juga memiliki beberapa opsi di sini:

Tampaknya banyak perusahaan besar yang menerbitkan REST API memaparkan searchkoleksi yang benar-benar hanya cara untuk mengirimkan parameter kueri untuk mengembalikan sumber daya.

GET http://server/api/search?q="type = myCollection & someField >= someval"

Yang akan mengembalikan koleksi sumber daya REST yang sepenuhnya memenuhi syarat seperti:

{
    "results" : 
       { [ 
             "location" : "http://server/api/myCollection/1",
             "location" : "http://server/api/myCollection/9",
             "location" : "http://server/api/myCollection/56"
         ]
       }
}

Atau Anda dapat mengizinkan sesuatu seperti MVEL sebagai parameter kueri.

Pertanyaan 3

Saya lebih suka sub-level daripada harus kembali dan meminta sumber daya lain dengan parameter kueri. Saya tidak percaya ada aturan apa pun. Anda dapat menerapkan kedua cara dan memungkinkan pemanggil untuk memutuskan mana yang lebih tepat berdasarkan pada bagaimana mereka pertama kali masuk ke dalam sistem.

Catatan

Saya tidak setuju tentang komentar keterbacaan dari orang lain. Meskipun demikian beberapa orang mungkin berpikir REST masih belum untuk konsumsi manusia. Ini untuk konsumsi mesin. Jika saya ingin melihat Tweet saya, saya menggunakan situs web reguler Twitters. Saya tidak melakukan REST GET dengan API mereka. Jika saya ingin melakukan sesuatu secara pemrograman dengan tweet saya maka saya menggunakan REST API mereka. Ya API harus dimengerti, tetapi Anda gteyang tidak buruk, itu hanya tidak intuitif.

Hal utama lainnya dengan REST adalah bahwa Anda harus dapat memulai kapan saja di API Anda dan menavigasi ke semua sumber daya terkait TANPA tahu URL persis dari sumber daya lain sebelumnya. Hasil GETKATA KERJA di REST harus mengembalikan URL REST lengkap dari sumber daya yang dirujuk. Jadi, alih-alih kueri yang mengembalikan ID Personobjek, itu akan mengembalikan URL yang Memenuhi Kualifikasi seperti http://server/api/people/13. Kemudian Anda selalu dapat menavigasi hasil secara terprogram meskipun URL berubah.

Respon terhadap komentar

Di dunia nyata sebenarnya ada hal-hal yang perlu terjadi yang tidak membuat, membaca, memperbarui atau menghapus (CRUD) sumber daya.

Tindakan tambahan dapat diambil pada sumber daya. Basis data relasional yang tipikal mendukung konsep Prosedur yang Disimpan. Ini adalah perintah tambahan yang dapat dieksekusi pada set data. REST pada dasarnya tidak memiliki konsep itu. Dan tidak ada alasan untuk itu. Jenis tindakan ini sempurna untuk Layanan Web RPC atau SOAP.

Ini adalah masalah umum yang saya lihat dengan REST API. Pengembang tidak menyukai batasan konseptual yang mengelilingi REST sehingga mereka mengadaptasinya untuk melakukan apa pun yang mereka inginkan. Itu mematahkannya dari menjadi layanan tenang. Pada dasarnya URL itu menjadi GETpanggilan pada servlets pseudo-REST.

Anda punya beberapa pilihan:

• Buat sumber daya tugas
• Mendukung POSTmemasukkan data tambahan ke sumber daya untuk melakukan suatu tindakan.
• Tambahkan perintah tambahan melalui SOAP Web Service.

Jika Anda menggunakan parameter kueri, HTTP VERB mana yang akan Anda gunakan untuk mengirim ulang email?

• GET- Apakah ini mengirim ulang email DAN mengembalikan data sumber daya? Bagaimana jika suatu sistem menyimpan URL itu dan memperlakukannya seperti URL unik untuk sumber daya itu. Setiap kali mereka menekan URL itu akan mengirim ulang email.
• POST - Anda sebenarnya tidak mengirim data baru ke sumber daya, hanya parameter kueri tambahan.

Berdasarkan semua persyaratan yang diberikan, melakukan POSTpada sumber daya dengan action fielddata POST akan menyelesaikan masalah.

Pertanyaan 1: Apakah pantas mencampurkan semacam aksi panggilan dengan URI sumber daya [atau] akan lebih baik untuk menentukan tindakan dan meneruskan id sumber daya itu?

Pertanyaan bagus. Dalam hal ini saya akan menyarankan Anda menggunakan pendekatan yang terakhir, yaitu tentukan tindakan dan berikan ID sumber daya untuk itu. Dengan cara ini, ketika sumber daya Anda pertama kali dimodifikasi, itu pada gilirannya memanggil /sendEmailtindakan (catatan: tidak perlu menyebutnya "kirim ulang") sebagai permintaan RESTful yang terpisah (yang nantinya dapat Anda panggil berulang kali, terlepas dari sumber daya yang sedang dimodifikasi ).

Pertanyaan 2: tentang penggunaan operator pembanding seperti:/collection?someField:gte=someval

Meskipun secara teknis ini ok, itu mungkin ide yang buruk. Salah satu prinsip utama REST adalah keterbacaan. Saya sarankan Anda melewati operator perbandingan sebagai parameter lain, misalnya: /collection?someField=someval&operator=gtedan tentu saja merancang API Anda sehingga memenuhi kasus default (jika operatorparameter tersebut tidak dimasukkan dalam URI).

Pertanyaan 3: Apakah benar-benar ada alasan bagus untuk REST URI lebih dari dua level?

Ya; untuk abstraksi. Saya telah melihat beberapa REST API yang menggunakan lapisan abstraksi melalui beberapa level URI, misalnya: /vehicles/cars/123atau /vehicles/bikes/123yang pada gilirannya memungkinkan Anda untuk bekerja dengan informasi berguna yang berkaitan dengan keduanya /vehiclesdan /vehicles/bikeskoleksi. Karena itu, saya bukan penggemar besar pendekatan ini; Anda jarang perlu melakukan ini dalam praktik, dan kemungkinan Anda dapat mendesain ulang API untuk menggunakan hanya 2 level.

Dan ya, seperti komentar di atas sarankan, di masa depan akan lebih baik untuk membagi pertanyaan Anda menjadi posting terpisah;)

Untuk pertanyaan 2, alternatif yang berbeda bisa lebih fleksibel: pertimbangkan setiap pencarian sumber daya yang dibuat pengguna sebelum menggunakan.

katakanlah Anda memiliki wadah "pencarian", di sana Anda melakukan POST /api/searches/dengan spesifikasi permintaan pada konten. bisa berupa JSON, XML, atau bahkan dokumen SQL, apa pun yang lebih mudah bagi Anda. Jika kueri mem-parse dengan benar, pencarian baru dibuat sebagai sumber daya baru dengan URI sendiri, katakanlah/api/searches/q123/

Kemudian, klien hanya GET /api/searches/q123/dapat mengambil hasil kueri.

Akhirnya, Anda bisa meminta klien untuk menghapus kueri, atau membersihkannya setelah menutup sesi.

Apakah pantas mencampurkan semacam aksi panggilan dengan URI sumber daya (mis. / Collection / 123? Action = resendEmail)? Apakah lebih baik untuk menentukan tindakan dan meneruskan id sumber daya ke sana (mis. / Collection / resendEmail? Id = 123)? Apakah ini cara yang salah untuk melakukannya? Secara tradisional (setidaknya dengan HTTP) tindakan yang dilakukan adalah metode permintaan (GET, POST, PUT, DELETE), tetapi tindakan tersebut tidak benar-benar memungkinkan tindakan khusus dengan sumber daya.

Tidak, itu tidak tepat, karena IRI adalah untuk mengidentifikasi sumber daya dan bukan operasi (namun ppl menggunakan metode ini mengesampingkan pendekatan untuk sementara waktu, dalam kasus ketika menggunakan metode non POST dan GET tidak didukung). Yang dapat Anda lakukan adalah mencari metode HTTP yang sesuai, atau membuat yang baru. POST dapat menjadi teman Anda dalam kasus ini (ppl menggunakannya jika mereka tidak dapat menemukan metode yang sesuai dan permintaan tersebut tidak diambil). Pendekatan lain untuk membuat sumber daya dari pengiriman email dan dengan demikian POST /emailsdapat mengirim surat tanpa membuat sumber daya nyata. Btw. Struktur URI tidak membawa semantik, jadi dari perspektif REST, tidak masalah jenis URI yang Anda gunakan. Yang penting adalah meta-data (misalnya hubungan tautan ) yang ditetapkan untuk tautan yang Anda kirim ke klien.

Gagasan terbaik yang saya buat sejauh ini adalah mengizinkan pengguna API untuk menentukannya sebagai tambahan untuk nama bidang (misalnya / koleksi? SomeField: gte = someval - untuk menunjukkan bahwa ia harus mengembalikan sumber daya di mana someField lebih besar daripada atau sama dengan (> =) apa pun itu. Apakah ini ide yang bagus? Ide yang buruk? Jika demikian, mengapa? Apakah ada cara yang lebih baik untuk memungkinkan pengguna menentukan jenis perbandingan untuk tampil dengan bidang dan nilai yang diberikan?

Anda tidak harus membuat bahasa permintaan sendiri. Saya lebih suka menggunakan yang sudah ada dan menambahkan beberapa deskripsi permintaan ke meta-data tautan. Anda sebaiknya menggunakan jenis media RDF (mis. JSON-LD) untuk melakukan itu atau menggunakan jenis MIME khusus (afaik tidak ada format non-RDF yang mendukung ini). Menggunakan standar yang ada memisahkan klien Anda dari server, itulah batasan antarmuka antarmuka yang seragam.

Itu akan setara dengan / anjing? Orang = 123. Apakah benar-benar ada alasan bagus untuk REST URI lebih dari dua level (/ collection / resource_id)?

Seperti yang saya sebutkan sebelumnya, struktur URI tidak masalah dari perspektif REST. Anda bisa menggunakan /x71fd823df2misalnya. Masih masuk akal bagi klien karena mereka memeriksa meta-data yang ditetapkan untuk tautan dan bukan struktur URI. Tujuan utama URI adalah mengidentifikasi sumber daya. Dalam standar URI mereka menyatakan bahwa lintasan berisi data hierarkis dan kueri berisi data non-hierarkis. Tetapi bisa sangat subjektif apa yang hirarkis. Itu sebabnya Anda bertemu berbagai level URI dan URI dengan kueri panjang.

Saya telah mencari tanpa henti selama berjam-jam tetapi belum menemukan jawaban untuk pertanyaan saya di mana saja (mungkin saya tidak tahu harus mencari apa?).

Anda harus membaca setidaknya kendala REST dari disertasi Fielding , standar HTTP , dan mungkin web API generasi ke-3 dari Markus.