Bagaimana cara membuat REST URL tanpa kata kerja?

283

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:

  1. Unggah parameter baru
  2. Dapatkan parameter terbaru
  3. Dapatkan parameter untuk tanggal bisnis tertentu
  4. Jadikan seperangkat parameter aktif
  5. 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:

  1. POST tempat Anda memasukkan file parameter dalam permintaan posting
  2. DAPATKAN URL pertama
  3. 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

??

Marcus Leon
sumber
3
Saya lebih suka PATCH daripada POST untuk pembaruan parsial.
user2016971

Jawaban:

71

Mungkin sesuatu seperti:

PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18

{ "active": true }
yfeldblum
sumber
1
POSTOK 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.
Andrey Vlasovskikh
19
PUT adalah untuk membuat sumber daya baru, atau menempatkan (secara keseluruhan, bukan sebagian) sumber daya baru di URL tertentu. Saya tidak melihat bagaimana PUT cocok dengan kasus ini.
Breton
30
Sebenarnya, POSTvs PUTtidak persis seperti insertvs update. PUTmemperbarui sumber daya yang sesuai dengan jalur yang diberikan, atau membuat sumber daya baru yang sesuai dengan jalur yang diberikan. POSTmenciptakan sumber daya baru di suatu tempat. Misalnya, PUT /blog/posts/3/comments/5akan memperbarui komentar yang sesuai, sementara POST /blog/posts/3/commentsakan membuat commentsumber daya baru (dan harus mengembalikan jalur ke sumber daya baru dalam respons).
yfeldblum
23
@Justice @Breton Perbedaan yang lebih penting PUTadalah idempoten sedangkan POSTtidak. Biasanya Anda harus memberi batasan sebanyak mungkin pada apa yang Anda berikan sebagai hasil. Tetap dengan PUTmemberikan lebih banyak informasi kepada klien layanan.
Andrey Vlasovskikh
3
Sumber daya juga bisa berupa / parameter / status dan badan permintaan bisa saja "aktif". Dengan begitu Anda entah bagaimana menempatkan seluruh sumber daya baru ke URL tertentu.
Carlos Aguayo
991

Prinsip umum untuk desain URI yang baik:

  • Jangan gunakan parameter kueri untuk mengubah status
  • Jangan gunakan jalur case campuran jika Anda bisa membantu; huruf kecil adalah yang terbaik
  • Jangan gunakan ekstensi khusus implementasi di URI Anda (.php, .py, .pl, dll.)
  • Jangan jatuh ke RPC dengan URI Anda
  • Apakah membatasi ruang URI Anda sebanyak mungkin
  • Jangan biarkan segmen jalur pendek
  • Lebih suka salah satu /resourceatau /resource/; buat 301 redirect dari yang tidak Anda gunakan
  • Apakah parameter sesuai urutan untuk sub-pemilihan sumber daya; yaitu pagination, permintaan pencarian
  • Do pindah barang dari URI yang harus di HTTP header atau badan

(Catatan: Saya tidak mengatakan "RESTful URI design"; URI pada dasarnya buram di REST.)

Prinsip umum untuk pilihan metode HTTP:

  • Jangan pernah menggunakan GET untuk mengubah status; ini adalah cara terbaik untuk membuat Googlebot merusak hari Anda
  • Jangan gunakan PUT kecuali Anda memperbarui seluruh sumber daya
  • Jangan gunakan PUT kecuali jika Anda juga dapat secara sah melakukan GET pada URI yang sama
  • Jangan gunakan POST untuk mengambil informasi yang berumur panjang atau yang mungkin masuk akal untuk di-cache
  • Jangan melakukan operasi yang tidak idempoten dengan PUT
  • Apakah penggunaan GET untuk sebanyak mungkin
  • Jangan gunakan POST dalam preferensi untuk PUT ketika ragu
  • Jangan gunakan POST setiap kali Anda harus melakukan sesuatu yang terasa seperti RPC
  • Apakah penggunaan PUT untuk kelas sumber daya yang lebih besar atau hirarki
  • Apakah penggunaan DELETE dalam preferensi untuk POST ke sumber daya menghapus
  • Do penggunaan GET untuk hal-hal seperti perhitungan, kecuali masukan Anda besar, dalam hal penggunaan POST

Prinsip umum desain layanan web dengan HTTP:

  • Jangan letakkan metadata di badan respons yang seharusnya ada di tajuk
  • Jangan letakkan metadata di sumber yang terpisah kecuali jika termasuk itu akan menciptakan overhead yang signifikan
  • Jangan gunakan kode status yang sesuai
    • 201 Createdsetelah membuat sumber daya; sumber daya harus ada pada saat respons dikirim
    • 202 Accepted setelah melakukan operasi dengan sukses atau membuat sumber daya secara tidak sinkron
    • 400 Bad Requestketika seseorang melakukan operasi pada data yang jelas palsu; untuk aplikasi Anda ini bisa menjadi kesalahan validasi; umumnya memesan 500 untuk pengecualian tanpa tertangkap
    • 401 Unauthorizedketika seseorang mengakses API Anda baik tanpa menyediakan Authorizationtajuk yang diperlukan atau ketika kredensial di dalamnya Authorizationtidak valid; jangan gunakan kode respons ini jika Anda tidak mengharapkan kredensial melalui Authorizationtajuk.
    • 403 Forbidden ketika seseorang mengakses API Anda dengan cara yang mungkin berbahaya atau jika tidak diotorisasi
    • 405 Method Not Allowed ketika seseorang menggunakan POST ketika mereka seharusnya menggunakan PUT, dll
    • 413 Request Entity Too Large ketika seseorang mencoba mengirimi Anda file berukuran besar yang tidak dapat diterima
    • 418 I'm a teapot ketika mencoba menyeduh kopi dengan teko
  • Apakah penggunaan header caching kapan pun Anda bisa
    • ETag header bagus ketika Anda dapat dengan mudah mengurangi sumber daya ke nilai hash
    • Last-Modified harus menunjukkan kepada Anda bahwa menjaga di sekitar timestamp kapan sumber daya diperbarui adalah ide yang baik
    • Cache-Controldan Expiresharus diberi nilai yang masuk akal
  • Lakukan apa saja untuk menghormati header caching dalam permintaan ( If-None-Modified, If-Modified-Since)
  • Do penggunaan pengalihan ketika mereka masuk akal, tetapi ini harus menjadi langka untuk layanan web

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.

Bob Aman
sumber
11
413 ditujukan untuk ukuran permintaan yang Anda kirim sehingga Anda dapat dengan sopan menolak seseorang mengirimi Anda data, sering kali bersamaan dengan 411 sehingga Anda memaksa orang untuk memberi tahu Anda berapa banyak yang dikirim. Untuk contoh yang diberikan terhadap 413, saya pikir 400 akan menjadi respons yang lebih tepat.
Garry Shutler
5
Memberi +1 karena ini adalah sumber yang bagus. Namun, ini adalah sumber daya umum dan tidak secara langsung menjawab pertanyaan. Idealnya ini harus mencakup paragraf tambahan dengan jawaban spesifik.
Samuel Neff
@ GarryShutler Bagus, Anda memang benar. Terima kasih atas hasil editnya.
Bob Aman
1
Ya, Anda hanya akan menggunakan PUT jika Anda menimpa seluruh objek. Namun, saya akan mengklaim bahwa PATCH atau POST masuk akal jika terjadi pembaruan sebagian sumber daya. PATCH lebih jelas dalam hal apa yang akan dilakukan operasi, tetapi karena tidak semua klien bahkan mampu mengeluarkan permintaan PATCH , itu sepenuhnya tepat untuk memungkinkan POST sebagai gantinya, dan saya bahkan mungkin melangkah lebih jauh dengan mengadvokasi bahwa POST harus selalu dibolehkan sebagai fallback jika PATCH digunakan.
Bob Aman
1
+1 untuk 409 kesalahan. Kesalahan 400 adalah sesuatu yang bisa diselesaikan dengan validasi sisi klien yang memadai. A 409 mengklarifikasi bahwa permintaan itu sendiri dapat diterima dan konsisten, tetapi bertentangan dengan beberapa aspek keadaan server (biasanya kontrol konkurensi, tetapi secara teoritis ada kendala non-input).
claytond
18

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 .

Apodaca kaya
sumber
1
Ini adalah poin yang sangat bagus. Sangat mudah untuk dilewatkan jika Anda dalam keadaan berpikir untuk memproses logika dan penalaran formal. Tidak masalah apa X asalkan cocok dengan bagian lain dengan cara yang valid. Faktor manusia hilang begitu saja.
Breton
1
Kadang-kadang saya merasa berguna untuk mengubah kata-kata menjadi "sumber daya pemrosesan" seperti "aktivator" atau "validator". Per RFC 2616 POST dapat digunakan untuk "Menyediakan blok data ... untuk proses penanganan data"
Darrel Miller
Dimengerti Dalam hal ini pengguna merujuk ke data sebagai "parameter" (atau "parameter risiko" atau yang serupa). Daftar parameter memang mengandung berbagai jenis pengaturan tetapi parameter selalu diunggah sebagai satu set lengkap (dalam file CSV).
Marcus Leon
@ Markus - itu terdengar seperti kasus yang sangat tidak biasa. Mungkin jika Anda menjelaskan apa yang dilakukan aplikasi Anda secara lebih rinci, kami dapat menawarkan saran yang lebih baik untuk mengidentifikasi sumber daya.
Rich Apodaca
1
"ketika Anda mendiskusikan aplikasi Anda dengan pengguna akhir apa kata-kata yang mereka gunakan berulang kali?" ... dan bagaimana jika mereka semua adalah kata kerja? XD
Amalgovinus
11

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:

GET [parametersurl]/validationresults

POST [paramatersurl]
body: {command:"activate"}

Tapi sekali lagi, yang mengaktifkannya adalah RPC, bukan REST.

Breton
sumber
Anda menyatakan poin yang menarik di sini. Bisakah Anda menguraikan sedikit lebih jauh bagaimana pendekatan RESTful untuk sesuatu seperti ini?
poezn
Saya telah menghabiskan sedikit waktu membaca tanggapan di sini, dan saya pikir keadilan mungkin untuk sesuatu. ia memodelkan properti individual dari objek parameter Anda sebagai sumber daya individu, dan menggunakan kata kerja PUT untuk mengganti konten properti itu di sumber daya itu. Ini memodelkan keadaan setiap objek sebagai kumpulan sumber daya, dan mengubah kondisi sebagai menempatkan atau menghapus atau memodifikasi sumber daya. Adapun validasi - Anda hanya perlu sumber daya yang secara ajaib menyatakan apakah parameternya valid atau tidak, seperti di atas dalam jawaban saya. Itu akan baik-baik saja, selama itu tidak memiliki efek samping.
Breton
Asalkan tentu saja, apa yang dilakukan "Aktifkan" hanyalah menetapkan satu properti menjadi true. Jika harus melakukan hal lain, maka itu masih belum tenang, dan saya tidak yakin bagaimana Anda akan memodelkannya dengan tenang.
Breton
Saya tidak berpikir Anda bisa mengatakan dua kasus terakhir tidak tenang. Akibatnya Aktifkan dan Validasi hanyalah cara tidak langsung untuk mengatakan sumber daya berubah ke keadaan baru di mesin negara. REST cukup mampu memodelkan ini.
Darrel Miller
@ Darrel, saya pikir Anda menunjukkan bagian dari REST yang mungkin menantang bagi banyak orang yang baru mengenal REST. Bagaimana Anda bisa menerapkan operasi "Validasi sumber daya x"? Saya pikir hal yang menantang adalah bahwa itu adalah operasi yang dapat mengakibatkan perubahan negara, tetapi negara baru adalah hasil dari permintaan yang dibuat.
Sean
6

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,

/ActiveParameters
/ValidatedParameters

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:

POST /ActiveParameters?parameter=/Parameters/{Id}

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.

Darrel Miller
sumber
1

Saya akan menyarankan sumber dan metode Meta berikut.

Jadikan parameter aktif dan / atau validasi:

> PUT /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Content-Type: application/json
> Connection: close
>
> {'active': true, 'require-valid': true}
>
< HTTP/1.1 200 OK
< Connection: close
<

Periksa apakah parameternya aktif dan valid:

> GET /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Connection: close
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Connection: close
<
< {
<     'active': true,
<     'require-valid': true,
<     'valid': {'status': false, 'reason': '...'}
< }
<
Andrey Vlasovskikh
sumber
Sejauh yang saya mengerti, pertanyaannya adalah tentang penamaan URL yang tenang, bukan tentang fungsinya, bukan?
poezn
2
Pertanyaan yang terbatas pada "RESTful URLs" adalah pertanyaan yang buruk dan tidak boleh dijawab. Pertanyaannya seharusnya diperluas untuk mempertimbangkan "sumber daya tenang, dengan metode dan URL yang terkait" - dan dijawab seperti itu.
yfeldblum
Seperti yang saya pahami, pertanyaannya adalah tentang konvensi penamaan URL dan metode HTTP yang harus ditanggapi sumber daya yang disebutkan.
Andrey Vlasovskikh
1

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.

Roman Vottner
sumber
0

Sunting: Memang URI akan mencegah GETpermintaan 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 Requestkode 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.

Derek Mortimer
sumber
URI dimaksudkan sebagai pengidentifikasi. Menggunakan URL tertentu seharusnya tidak memiliki efek samping. Bayangkan apa yang akan dilakukan proxy dengan itu.
Breton
2
atau google, dalam hal ini. Saya pernah membaca cerita tentang toko web yang semua produknya dihapus oleh google karena kebodohan semacam ini.
Breton
0

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:

http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000

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.

jmucchiello
sumber
5
Saya pikir ini agak konyol untuk menggunakan garis miring di sini, apa yang salah dengan amort_cal? Date = 2009-10-20 & type = 30yrsfixed & period = bulanan & tarif = 5.0 & initialamount = 200000? REST tidak peduli asalkan itu sumber daya. Namun, spesifikasi URI tidak peduli. Bagaimana Anda membayangkan tautan relatif untuk bekerja dengan skema seperti ini?
Breton
Meskipun demikian, Anda mengemukakan poin yang bagus. Apakah "parameter" ini bahkan perlu disimpan di sisi server? Jika itu hanya perhitungan satu kali, mengapa tidak membuat ruang virtual, di mana parameternya ada di URL. Selama Anda tidak mengubah keadaan internal, itu akan baik-baik saja.
Breton
1
Dan "parameter" tidak berlaku untuk "sumber daya". Sumber daya adalah entitas tunggal dengan pengidentifikasi unik. URL saya mengidentifikasi satu sumber daya. URL berparameter menunjukkan koleksi sumber daya yang Anda pilih di antara menggunakan parameter.
jmucchiello
2
REST tidak didasarkan pada "CRUDing Resources". Menempelkan semua parameter kueri Anda ke dalam segmen jalur tidak secara otomatis membuat antarmuka RESTful karena sekarang Anda dapat memanggil setiap permutasi sebagai sumber daya. Sayangnya tidak ada proses ajaib yang dapat Anda terapkan untuk mengidentifikasi seperti apa sumber daya dalam sistem Anda. Itu membutuhkan desain yang hati-hati, bukan formula mekanis.
Darrel Miller
2
Sekali lagi, arsitektur REST tidak PEDULI apa yang ada di URL. URL dimaksudkan untuk menjadi buram . Tidak masalah untuk beristirahat apakah Anda menggunakan garis miring, titik koma, atau unicode heart sebagai pemisah. Baca ini, dan jawablah ini - bukan apa yang Anda bayangkan saya katakan.
Breton