Saya kesulitan menentukan cara mendesain URL yang tenang. Saya semua untuk pendekatan tenang menggunakan URL dengan kata benda dan bukan kata kerja tidak mengerti bagaimana melakukan ini.
Kami menciptakan layanan untuk mengimplementasikan kalkulator keuangan. Kalkulator ini mengambil banyak parameter yang akan kami unggah melalui file CSV. Kasus penggunaan akan melibatkan:
- Unggah parameter baru
- Dapatkan parameter terbaru
- Dapatkan parameter untuk tanggal bisnis tertentu
- Jadikan seperangkat parameter aktif
- Validasi sekumpulan parameter
Saya mengumpulkan pendekatan yang tenang adalah memiliki jenis URL berikut:
/parameters
/parameters/12-23-2009
Anda dapat mencapai tiga kasus penggunaan pertama dengan:
- POST tempat Anda memasukkan file parameter dalam permintaan posting
- DAPATKAN URL pertama
- DAPATKAN URL kedua
Tetapi bagaimana Anda melakukan use case ke-4 dan ke-5 tanpa kata kerja? Tidakkah Anda memerlukan URL seperti:
/parameters/ID/activate
/parameters/ID/validate
??
rest
restful-url
Marcus Leon
sumber
sumber
Jawaban:
Mungkin sesuatu seperti:
sumber
POST
OK jika Anda perlu melakukan "prosedur" seperti memverifikasi parameter setiap kali Anda mengirim permintaan. Tetapi ketika Anda mengubah (aplikasi) keadaan sumber daya, Anda benar-benar memperbarui sumber daya yang ada, tidak membuat beberapa sumber daya baru atau memposting permintaan pemrosesan.POST
vsPUT
tidak persis sepertiinsert
vsupdate
.PUT
memperbarui sumber daya yang sesuai dengan jalur yang diberikan, atau membuat sumber daya baru yang sesuai dengan jalur yang diberikan.POST
menciptakan sumber daya baru di suatu tempat. Misalnya,PUT /blog/posts/3/comments/5
akan memperbarui komentar yang sesuai, sementaraPOST /blog/posts/3/comments
akan membuatcomment
sumber daya baru (dan harus mengembalikan jalur ke sumber daya baru dalam respons).PUT
adalah idempoten sedangkanPOST
tidak. Biasanya Anda harus memberi batasan sebanyak mungkin pada apa yang Anda berikan sebagai hasil. Tetap denganPUT
memberikan lebih banyak informasi kepada klien layanan.Prinsip umum untuk desain URI yang baik:
/resource
atau/resource/
; buat 301 redirect dari yang tidak Anda gunakan(Catatan: Saya tidak mengatakan "RESTful URI design"; URI pada dasarnya buram di REST.)
Prinsip umum untuk pilihan metode HTTP:
Prinsip umum desain layanan web dengan HTTP:
201 Created
setelah membuat sumber daya; sumber daya harus ada pada saat respons dikirim202 Accepted
setelah melakukan operasi dengan sukses atau membuat sumber daya secara tidak sinkron400 Bad Request
ketika seseorang melakukan operasi pada data yang jelas palsu; untuk aplikasi Anda ini bisa menjadi kesalahan validasi; umumnya memesan 500 untuk pengecualian tanpa tertangkap401 Unauthorized
ketika seseorang mengakses API Anda baik tanpa menyediakanAuthorization
tajuk yang diperlukan atau ketika kredensial di dalamnyaAuthorization
tidak valid; jangan gunakan kode respons ini jika Anda tidak mengharapkan kredensial melaluiAuthorization
tajuk.403 Forbidden
ketika seseorang mengakses API Anda dengan cara yang mungkin berbahaya atau jika tidak diotorisasi405 Method Not Allowed
ketika seseorang menggunakan POST ketika mereka seharusnya menggunakan PUT, dll413 Request Entity Too Large
ketika seseorang mencoba mengirimi Anda file berukuran besar yang tidak dapat diterima418 I'm a teapot
ketika mencoba menyeduh kopi dengan tekoETag
header bagus ketika Anda dapat dengan mudah mengurangi sumber daya ke nilai hashLast-Modified
harus menunjukkan kepada Anda bahwa menjaga di sekitar timestamp kapan sumber daya diperbarui adalah ide yang baikCache-Control
danExpires
harus diberi nilai yang masuk akalIf-None-Modified
,If-Modified-Since
)Sehubungan dengan pertanyaan spesifik Anda, POST harus digunakan untuk # 4 dan # 5. Operasi ini berada di bawah pedoman "seperti RPC" di atas. Untuk # 5, ingatlah bahwa POST tidak harus digunakan
Content-Type: application/x-www-form-urlencoded
. Ini bisa dengan mudah menjadi muatan JSON atau CSV.sumber
Setiap kali Anda membutuhkan kata kerja baru, pikirkan untuk mengubah kata kerja itu menjadi kata benda. Misalnya, ubah 'aktifkan' menjadi 'aktivasi', dan 'validasi' menjadi 'validasi'.
Tetapi hanya dari apa yang Anda tulis saya akan mengatakan aplikasi Anda memiliki masalah yang jauh lebih besar.
Setiap kali suatu sumber daya yang disebut 'parameter' diusulkan, ia harus mengirimkan tanda merah di benak setiap anggota tim proyek. 'parameter' secara harfiah dapat diterapkan ke sumber daya apa pun; itu tidak cukup spesifik.
Apa sebenarnya yang dilambangkan oleh 'parameter'? Mungkin sejumlah hal berbeda, masing-masing harus memiliki sumber daya terpisah yang didedikasikan untuk itu.
Cara lain untuk mendapatkan ini - ketika Anda mendiskusikan aplikasi Anda dengan pengguna akhir (mereka yang mungkin tahu sedikit tentang pemrograman) apa kata-kata yang mereka gunakan berulang kali?
Itulah kata-kata yang harus Anda rancang di sekitar aplikasi Anda.
Jika Anda belum memiliki konversi ini dengan calon pengguna - hentikan semuanya sekarang dan jangan menulis baris kode lain sampai Anda melakukannya! Hanya dengan demikian tim Anda akan memiliki gagasan tentang apa yang perlu dibangun.
Saya tidak tahu apa-apa tentang perangkat lunak keuangan, tetapi jika saya harus menebak, saya akan mengatakan beberapa sumber daya mungkin menggunakan nama seperti "Laporan", "Pembayaran", "Transfer", dan "Mata Uang".
Ada sejumlah buku bagus tentang proses desain perangkat lunak ini. Dua yang bisa saya rekomendasikan adalah Desain dan Analisis Pola Domain Driven .
sumber
Desain URL Anda tidak ada hubungannya dengan apakah aplikasi Anda tenang atau tidak. Frase "RESTful URLs" karenanya tidak masuk akal.
Saya pikir Anda harus melakukan lebih banyak membaca tentang apa sebenarnya REST. REST memperlakukan URL sebagai buram, dan karena itu tidak tahu apa yang ada di dalamnya, apakah ada kata kerja atau kata benda atau apa pun. Anda mungkin masih ingin mendesain URL Anda, tetapi itu tentang UI, bukan REST.
Yang mengatakan, mari kita ke pertanyaan Anda: Dua kasus terakhir tidak tenang dan tidak cocok dengan segala jenis skema yang tenang. Itulah yang Anda sebut RPC. Jika Anda serius tentang REST, Anda harus memikirkan kembali cara kerja aplikasi Anda dari bawah ke atas. Entah itu atau tinggalkan REST dan lakukan aplikasi Anda sebagai aplikasi RPC.
Hrmmm mungkin tidak.
Idenya di sini adalah bahwa Anda harus memperlakukan semuanya sebagai sumber daya, jadi setelah satu set parameter memiliki URL yang dapat Anda gunakan untuk referensi, Anda cukup menambahkan:
Tapi sekali lagi, yang mengaktifkannya adalah RPC, bukan REST.
sumber
Persyaratan aktivasi dan validasi adalah situasi di mana Anda berusaha mengubah status sumber daya. Tidak ada bedanya dengan membuat pesanan "selesai", atau permintaan lain "dikirim". Ada banyak cara untuk memodelkan jenis perubahan negara ini tetapi satu yang saya temukan yang sering berhasil adalah menciptakan sumber daya pengumpulan untuk sumber daya dari negara yang sama dan kemudian memindahkan sumber daya di antara koleksi untuk mempengaruhi negara.
mis. Buat beberapa sumber seperti,
Jika Anda ingin membuat satu set parameter aktif, kemudian tambahkan set itu ke koleksi ActiveParameters. Anda bisa melewati set parameter sebagai badan entitas, atau Anda bisa meneruskan url sebagai parameter kueri, sebagai berikut:
Hal yang sama dapat dilakukan dengan / ValidatedParameters. Jika Parameter tidak valid maka server dapat mengembalikan "Permintaan Buruk" ke permintaan untuk menambahkan parameter ke pengumpulan parameter yang divalidasi.
sumber
Saya akan menyarankan sumber dan metode Meta berikut.
Jadikan parameter aktif dan / atau validasi:
Periksa apakah parameternya aktif dan valid:
sumber
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 kasus
application/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: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-urlencoded
format representasi yang dikirim ke lokasi target yang disebutkan melalui metode permintaan HTTP yang ditentukan,POST
dalam hal ini. Jika kita masuk1
kefirstNumber
bidang input dan2
kesecondNumber
bidang 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:
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
preload
tautan 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-urlencoded
representasi 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 keduanyatext/csv
sebagaimana 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/csv
secara 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
PUT
ditetapkannya, maka berpotensi mengirimkan seluruh konfigurasi melalui atau menjadi pandai tentang perubahan yang dilakukan dan hanya melakukan pembaruan parsial melaluiPATCH
. 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:
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 menjadi
text/csv
lalu 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.sumber
Sunting: Memang URI akan mencegah
GET
permintaan dari sisa idempoten.Namun untuk validasi, penggunaan kode status HTTP untuk memberi tahu validitas permintaan (untuk membuat yang baru atau memodifikasi 'parameter' yang ada) akan cocok dengan model Restful.
Laporkan kembali dengan
400 Bad Request
kode status jika data yang dikirim adalah / tidak valid dan permintaan harus diubah sebelum dikirim kembali ( HTTP / 1.1 Status Codes ).Ini bergantung pada validasi pada waktu pengiriman, daripada menunda seperti pada use case Anda. Jawaban lain memiliki solusi yang sesuai untuk skenario itu.
sumber
Di lingkungan REST, setiap URL adalah sumber daya yang unik. Apa sumber daya Anda? Kalkulator keuangan benar-benar tidak memiliki sumber daya yang jelas. Anda perlu menggali parameter yang Anda panggil dan mengeluarkan sumber dayanya. Misalnya, kalender amortisasi untuk pinjaman mungkin merupakan sumber daya. URL untuk kalender dapat mencakup tanggal mulai, istilah (dalam bulan atau tahun), periode (ketika bunga digabungkan), suku bunga, dan prinsip awal. Dengan semua nilai itu, Anda memiliki kalender pembayaran tertentu:
Sekarang, saya tidak tahu apa yang Anda hitung, tetapi konsep Anda tentang daftar parameter tidak terdengar tenang. Seperti kata orang lain, persyaratan Anda di atas terdengar lebih XMLRPC. Jika Anda mencoba untuk REST, Anda perlu kata benda. Perhitungan bukanlah kata benda, melainkan kata kerja yang bekerja pada kata benda. Anda perlu memutarnya untuk menarik kata benda dari kalori Anda.
sumber