Saya merasa agak sedih melihat bahwa setelah lebih dari 10 tahun tidak ada jawaban yang benar-benar menyatakan bagaimana hal seperti yang diminta dalam OP dapat dirancang dalam arsitektur REST, maka saya merasa perlu untuk melakukan ini sekarang.
Yang pertama, apa itu ISTIRAHAT ?! Singkatan REST atau ReST singkatan dari "Representational State Transfer" dan mendefinisikan pertukaran negara sumber daya dalam format representasi tertentu. Format representasi sesuai dengan jenis media yang dinegosiasikan. Dalam kasusapplication/html format representasi mungkin aliran konten teks yang diformat HTML yang diberikan di browser, mungkin setelah menerapkan beberapa format stylesheet untuk memposisikan elemen tertentu di lokasi tertentu.
REST pada prinsipnya adalah generalisasi dari Web yang dapat dijelajahi yang kita semua tahu, meskipun menargetkan semua jenis aplikasi dan bukan hanya browser. Oleh karena itu, berdasarkan desain, konsep yang sama yang berlaku untuk Web juga berlaku untuk arsitektur REST. Sebuah pertanyaan seperti bagaimana mencapai sesuatu dengan cara "RESTful" diselesaikan dengan menjawab pertanyaan bagaimana mencapai sesuatu di halaman Web dan kemudian menerapkan konsep yang sama ke lapisan aplikasi.
Kalkulator berbasis web biasanya dimulai dengan beberapa "halaman" yang memungkinkan Anda untuk memasukkan beberapa nilai untuk dihitung sebelum mengirim data yang dimasukkan ke server. Dalam HTML ini biasanya dicapai melalui <form>elemen HTML yang mengajarkan klien tentang parameter yang tersedia untuk ditetapkan, lokasi target untuk mengirim permintaan, serta format representasi untuk diterapkan saat mengirim data input. Ini bisa yaitu terlihat seperti ini:
<html>
<head>
...
</head>
<body>
<form action="/../someResource" method="post" enctype="application/x-www-form-urlencoded">
<label for="firstNumber">First number:</label>
<input type="number" id="firstNumber" name="firstNumber"/>
<label for="secondNumber">Second number:</label>
<input type="number" id="secondNumber" name="secondNumber"/>
<input type="submit" value="Add numbers"/>
</form>
</body>
</html>
Sampel di atas yaitu menyatakan bahwa ada dua bidang input yang dapat diisi baik oleh pengguna atau oleh automata lain, dan bahwa ketika menerapkan elemen input kirim, browser menangani pemformatan data input ke dalam application/x-www-form-urlencodedformat representasi yang dikirim ke lokasi target yang disebutkan melalui metode permintaan HTTP yang ditentukan, POSTdalam hal ini. Jika kita masuk 1ke firstNumberbidang input dan 2ke secondNumberbidang input, browser akan menghasilkan representasifirstNumber=1&secondNumber=2 dan mengirim ini sebagai muatan tubuh dari permintaan aktual ke sumber daya target.
Karenanya, permintaan HTTP mentah yang dikeluarkan ke server mungkin terlihat seperti ini:
POST /../someResource
Host: www.acme.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Accept: application/html
firstNumber=1&secondNumber=2
Server dapat melakukan perhitungan dan merespons dengan halaman HTML lebih lanjut yang berisi hasil perhitungan, karena permintaan menunjukkan bahwa klien memahami format ini.
Seperti yang ditunjukkan Breton, tidak ada yang namanya URL "RESTful" atau URI. URI / URL adalah jenisnya sendiri dan tidak boleh menyampaikan makna apa pun kepada klien / pengguna. Dalam sampel kalkulator di atas, pengguna sama sekali tidak tertarik ke mana harus mengirim data ke sana, hanya tertarik bahwa setelah memicu bidang masukan kirim permintaan dikirim. Semua informasi yang diperlukan yang diperlukan untuk melakukan tugas harus sudah diberikan oleh server.
Peramban juga mungkin tidak menyadari bahwa permintaan itu sebenarnya memberi makan kalkulator dengan beberapa parameter input, bisa juga semacam formulir pemesanan yang mengembalikan hanya representasi formulir berikutnya untuk melanjutkan proses pemesanan atau jenis yang sama sekali berbeda. sumber. Ini hanya melakukan apa yang dituntut spesifikasi HTML dalam kasus seperti itu dan tidak peduli apa yang sebenarnya dilakukan server. Konsep ini memungkinkan browser untuk menggunakan format representasi yang sama untuk melakukan semua hal seperti memesan beberapa barang dari toko online pilihan Anda, mengobrol dengan teman-teman terbaik Anda, masuk ke akun online dan sebagainya.
The affordance dari unsur-unsur tertentu, seperti dalam menyerahkan kasus field input yang biasanya diberikan tombol seperti, mendefinisikan apa yang harus Anda untuk dengan itu. Dalam hal tombol atau tautan pada dasarnya memberitahu Anda untuk mengkliknya. Elemen-elemen lain dapat memberikan harga yang berbeda. Keterjangkauan seperti itu juga dapat dinyatakan melalui tautan-hubungan seperti misalnya dengan preloadtautan beranotasi yang pada dasarnya memberi tahu klien bahwa ia sudah dapat memuat konten dari sumber daya yang tertaut di latar belakang karena kemungkinan besar pengguna akan mengambil konten ini selanjutnya. Tentu saja, hubungan tautan semacam itu harus distandarisasi atau mengikuti mekanisme ekstensi untuk jenis hubungan seperti yang didefinisikan oleh tautan Web .
Ini adalah konsep dasar yang digunakan di Web dan yang juga harus digunakan dalam arsitektur REST. Menurut "Paman Bob" Robert C. Martin arsitektur adalah tentang niat dan maksud di balik arsitektur REST adalah decoupling klien dari server untuk memungkinkan server untuk berkembang secara bebas di masa depan tanpa harus takut mereka melanggar klien. Sayangnya ini membutuhkan banyak disiplin karena sangat mudah untuk memperkenalkan kopling atau menambahkan solusi perbaikan cepat untuk menyelesaikan pekerjaan dan melanjutkan. Seperti yang ditunjukkan Jim Webber dalam arsitektur REST, Anda, sebagai penyedia layanan, harus berupaya mendesain protokol aplikasi domain yang mirip dengan permainan komputer berbasis teks tahun 70-an. yang akan ditindaklanjuti klien hingga mereka mencapai akhir proses.
Apa yang banyak disebut API "REST" sayangnya dalam kenyataannya adalah segalanya. Anda melihat pertukaran sebagian besar data berbasis JSON yang ditentukan dalam dokumentasi eksternal khusus API yang biasanya sulit diintegrasikan secara dinamis dengan cepat. Format bagaimana permintaan harus terlihat seperti juga hardcoded ke dalam dokumentasi eksternal yang mengarah ke banyak implementasi menafsirkan URI ke mengembalikan jenis yang telah ditentukanalih-alih menggunakan beberapa format representasi umum yang dinegosiasikan dimuka. Ini mencegah server untuk berubah karena klien sekarang mengharapkan untuk menerima format data tertentu (catatan bukan format representasi!) Untuk URI yang telah ditentukan. Pertukaran format data khusus ini selanjutnya mencegah klien berinteraksi dengan API lain karena "format data" biasanya pasang ke API tertentu. Kami tahu konsep ini dari masa lalu dari teknologi RPC seperti Corba, RMI atau SOAP yang kami kutuk sebagai sesuatu yang jahat, meskipun Peppol pindah lagi dengan mengganti AS2 dengan AS4 sebagai protokol transfer default baru-baru ini.
Sehubungan dengan pertanyaan aktual yang diajukan, mengirim data sebagai file csv tidak berbeda dengan menggunakan application/x-www-form-urlencodedrepresentasi atau hal serupa. Jim Webber memperjelas bahwa bagaimanapun HTTP hanyalah sebuah protokol transport yang domain aplikasinya adalah transfer dokumen melalui Web . Klien dan server harus setidaknya mendukung keduanya text/csvsebagaimana didefinisikan dalam RFC 7111 . File CSV ini dapat dihasilkan sebagai konsekuensi dari pemrosesan jenis media yang mendefinisikan elemen formulir, elemen target atau atribut untuk mengirim permintaan, serta metode HTTP untuk melakukan pengunggahan konfigurasi.
Ada beberapa jenis media yang mendukung formulir seperti HTML , Formulir HAL , halform , ion , atau Hydra . Saya saat ini, meskipun, tidak mengetahui jenis media yang secara otomatis dapat menyandikan data input text/csvsecara langsung sehingga orang mungkin perlu didefinisikan dan didaftarkan ke registri jenis media IANA .
Mengunggah dan mengunduh set parameter yang lengkap seharusnya tidak menjadi masalah. Seperti disebutkan sebelumnya, URI target tidak relevan karena klien hanya akan menggunakan URI untuk mengambil konten baru untuk diproses. Memfilter berdasarkan tanggal bisnis juga tidak sulit. Namun di sini server harus klien dengan semua kemungkinan yang dapat dipilih oleh klien. Dalam beberapa tahun terakhir GraphQL dan RestQL berevolusi yang memperkenalkan bahasa seperti SQL yang dapat ditargetkan pada titik akhir tertentu untuk mendapatkan respons yang difilter. Namun, dalam arti REST yang sebenarnya, ini melanggar ide di balik REST sebagai a) GraphQL yaitu hanya menggunakan titik akhir tunggal yang entah bagaimana mencegah penggunaan caching yang optimal dan b) membutuhkan pengetahuan tentang bidang yang tersedia di tempat yang jauh, yang dapat menyebabkan pengenalan kopling klien ke model data dasar sumber daya.
Mengaktifkan atau menonaktifkan parameter konfigurasi tertentu hanyalah masalah memicu kontrol hypermedia yang menyediakan keterjangkauan ini. Dalam bentuk HTML ini bisa berupa kotak centang sederhana atau pilihan multi-baris dalam daftar atau semacam itu. Bergantung pada bentuk dan metode apa yang PUTditetapkannya, maka berpotensi mengirimkan seluruh konfigurasi melalui atau menjadi pandai tentang perubahan yang dilakukan dan hanya melakukan pembaruan parsial melalui PATCH. Yang terakhir pada dasarnya membutuhkan kalkulasi representasi perubahan ke yang diperbarui dan memberi makan server dengan langkah-langkah yang diperlukan untuk mengubah representasi saat ini menjadi yang diinginkan. Menurut spesifikasi PATH ini harus dilakukan dalam transaksi sehingga semua atau tidak ada langkah-langkah yang diterapkan.
HTTP memungkinkan dan mendorong server untuk memvalidasi permintaan yang diterima dimuka sebelum menerapkan perubahan. Untuk PUT , spesifikasi menyatakan:
Server asal HARUS memverifikasi bahwa representasi PUT konsisten dengan kendala yang dimiliki server untuk sumber daya target yang tidak dapat atau tidak akan diubah oleh PUT. Ini sangat penting ketika server asal menggunakan informasi konfigurasi internal yang terkait dengan URI untuk mengatur nilai-nilai untuk metadata representasi pada respons GET. Ketika representasi PUT tidak konsisten dengan sumber daya target, server asal HARUS membuatnya konsisten, dengan mengubah representasi atau mengubah konfigurasi sumber daya, atau merespons dengan pesan kesalahan yang sesuai yang berisi informasi yang cukup untuk menjelaskan mengapa representasi tidak cocok. Kode status 409 (Konflik) atau 415 (Jenis Media Tidak Didukung) disarankan,
Misalnya, jika sumber daya target dikonfigurasi untuk selalu memiliki Tipe-Konten "teks / html" dan representasi yang PUT memiliki Tipe-Konten "gambar / jpeg", server asal harus melakukan salah satu dari:
Sebuah. mengkonfigurasi ulang sumber daya target untuk mencerminkan jenis media baru;
b. mengubah representasi PUT menjadi format yang konsisten dengan sumber daya sebelum menyimpannya sebagai status sumber daya baru; atau,
c. tolak permintaan dengan respons 415 (Jenis Media yang Tidak Didukung) yang menunjukkan bahwa sumber daya target terbatas pada "teks / html", mungkin termasuk tautan ke sumber daya yang berbeda yang akan menjadi target yang sesuai untuk representasi baru.
HTTP tidak mendefinisikan secara tepat bagaimana metode PUT mempengaruhi keadaan server asal melebihi apa yang bisa diekspresikan oleh maksud permintaan agen pengguna dan semantik dari respons server asal. ...
Untuk meringkas posting ini, Anda harus menggunakan jenis media yang ada yang memungkinkan Anda untuk mengajar klien tentang parameter input yang diperlukan atau didukung, lokasi target untuk mengirim permintaan, operasi yang digunakan serta jenis media yang digunakan. permintaan harus diformat dalam, atau tentukan sendiri yang Anda daftarkan dengan IANA. Yang terakhir mungkin diperlukan jika Anda ingin mengonversi input menjaditext/csvlalu unggah representasi CSV ke server. Validasi harus terjadi sebelum perubahan diterapkan pada sumber daya. URI yang sebenarnya seharusnya tidak relevan dengan klien selain untuk menentukan ke mana harus mengirim permintaan dan dengan demikian dapat dipilih secara bebas oleh Anda, pelaksana layanan. Dengan mengikuti langkah-langkah ini Anda mendapatkan kebebasan untuk mengubah sisi server Anda kapan saja dan klien tidak akan merusaknya jika mereka mendukung jenis media yang digunakan.