Saya ingin merancang titik akhir istirahat saya dengan metode yang sesuai untuk skenario berikut.
Ada sebuah grup. Setiap grup memiliki status. Grup dapat diaktifkan atau dinonaktifkan oleh admin.
Haruskah saya mendesain titik akhir saya sebagai
PUT /groups/api/v1/groups/{group id}/status/activate
ATAU
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
http
rest
http-put
http-method
http-patch
java_geek
sumber
sumber
activate
" tidak memadai konstruksi tenang. Anda mungkin mencoba memperbaruistatus
ke "aktif" atau "tidak aktif". dalam hal ini Anda dapat PATCH ke.../status
dengan string "aktif" atau "tidak aktif" di tubuh. Atau jika Anda mencoba memperbarui boolean distatus.active
, Anda dapat PATCH ke.../status/active
dengan boolean di dalam tubuhJawaban:
The
PATCH
metode adalah pilihan yang tepat di sini karena Anda sedang memperbarui sumber daya yang ada - ID grup.PUT
seharusnya hanya digunakan jika Anda mengganti sumber daya secara keseluruhan.Informasi lebih lanjut tentang modifikasi sumber daya parsial tersedia di RFC 5789 . Secara khusus,
PUT
metode ini dijelaskan sebagai berikut:sumber
The R di SISA singkatan sumber daya
(Yang tidak benar, karena mewakili Representasi, tetapi itu adalah trik yang baik untuk mengingat pentingnya Sumberdaya di REST).
Tentang
PUT /groups/api/v1/groups/{group id}/status/activate
: Anda tidak memperbarui "aktifkan". "Aktifkan" bukanlah sesuatu, itu kata kerja. Kata kerja tidak pernah sumber daya yang baik. Aturan praktis: jika tindakan, kata kerja, ada di URL, itu mungkin tidak tenang .Apa yang kamu lakukan? Entah Anda "menambahkan", "menghapus" atau "memperbarui" suatu aktivasi pada suatu Grup, atau jika Anda lebih suka: memanipulasi "status" -asumber daya pada suatu Grup. Secara pribadi, saya akan menggunakan "aktivasi" karena mereka kurang ambigu daripada konsep "status": membuat status ambigu, membuat aktivasi tidak.
POST /groups/{group id}/activation
Membuat (atau meminta pembuatan) aktivasi.PATCH /groups/{group id}/activation
Memperbarui beberapa detail dari aktivasi yang ada. Karena grup hanya memiliki satu aktivasi, kami tahu sumber daya aktivasi yang kami maksud.PUT /groups/{group id}/activation
Menyisipkan-atau-menggantikan aktivasi yang lama. Karena grup hanya memiliki satu aktivasi, kami tahu sumber daya aktivasi yang kami maksud.DELETE /groups/{group id}/activation
Akan membatalkan, atau menghapus aktivasi.Pola ini berguna ketika "aktivasi" Grup memiliki efek samping, seperti pembayaran yang dilakukan, surat yang dikirim dan sebagainya. Hanya POST dan PATCH yang memiliki efek samping seperti itu. Ketika mis. Penghapusan aktivasi harus, katakanlah, beri tahu pengguna melalui surat, DELETE bukanlah pilihan yang tepat; dalam hal ini Anda mungkin ingin menciptakan sumber daya penonaktifan :
POST /groups/{group_id}/deactivation
.Adalah ide yang baik untuk mengikuti pedoman ini, karena kontrak standar ini membuatnya sangat jelas untuk klien Anda, dan semua proksi dan lapisan antara klien dan Anda, tahu kapan aman untuk mencoba lagi, dan kapan tidak. Katakanlah klien berada di suatu tempat dengan wifi yang tidak stabil, dan penggunanya mengklik "nonaktifkan", yang memicu
DELETE
: Jika gagal, klien hanya dapat mencoba lagi, sampai mendapat 404, 200 atau apa pun yang dapat ditangani. Tetapi jika itu memicu aPOST to deactivation
ia tahu untuk tidak mencoba lagi: POST menyiratkan ini.Setiap klien sekarang memiliki kontrak, yang, ketika diikuti, akan melindungi terhadap pengiriman 42 email "grup Anda telah dinonaktifkan", hanya karena perpustakaan HTTP-nya terus mencoba kembali panggilan ke backend.
Memperbarui satu atribut: gunakan PATCH
PATCH /groups/{group id}
Jika Anda ingin memperbarui atribut. Misalnya "status" bisa menjadi atribut pada Grup yang dapat diatur. Atribut seperti "status" seringkali merupakan kandidat yang baik untuk dibatasi pada daftar putih nilai. Contoh menggunakan beberapa skema JSON yang tidak ditentukan:
Mengganti sumber daya, tanpa efek samping menggunakan PUT.
PUT /groups/{group id}
Jika Anda ingin mengganti seluruh Grup. Ini tidak selalu berarti bahwa server benar-benar membuat grup baru dan membuang yang lama, misalnya id mungkin tetap sama. Tetapi untuk klien, inilah yang dapat PUT maksud: klien harus berasumsi bahwa ia mendapatkan item yang sama sekali baru, berdasarkan respons server.
Klien harus, dalam hal
PUT
permintaan, selalu mengirim seluruh sumber daya, memiliki semua data yang diperlukan untuk membuat item baru: biasanya data yang sama seperti yang dibutuhkan oleh POST-create.Persyaratan yang sangat penting
PUT
adalah idempoten: jika Anda memerlukan efek samping saat memperbarui Grup (atau mengubah aktivasi), Anda harus menggunakannyaPATCH
. Jadi, ketika pembaruan menghasilkan misalnya mengirim surat, jangan gunakanPUT
.sumber
Saya akan merekomendasikan menggunakan PATCH, karena 'grup' sumber daya Anda memiliki banyak properti tetapi dalam kasus ini, Anda hanya memperbarui bidang aktivasi (modifikasi parsial)
menurut RFC5789 ( https://tools.ietf.org/html/rfc5789 )
Juga, lebih terinci,
Kode respons untuk PATCH adalah
lihat juga thttp: //restcookbook.com/HTTP%20Methods/patch/
sumber
Karena Anda ingin mendesain API menggunakan gaya arsitektur REST, Anda perlu memikirkan use case Anda untuk memutuskan konsep mana yang cukup penting untuk diekspos sebagai sumber daya. Jika Anda memutuskan untuk mengekspos status grup sebagai sub-sumber daya, Anda dapat memberikannya URI berikut dan menerapkan dukungan untuk metode GET dan PUT:
Kelemahan dari pendekatan ini atas PATCH untuk modifikasi adalah bahwa Anda tidak akan dapat membuat perubahan pada lebih dari satu properti grup secara atom dan transaksi. Jika perubahan transaksional penting maka gunakan PATCH.
Jika Anda memutuskan untuk mengekspos status sebagai sub-sumber daya grup, itu harus menjadi tautan dalam representasi grup. Misalnya jika agen mendapat grup 123 dan menerima XML, badan respons dapat berisi:
Diperlukan hyperlink untuk memenuhi hypermedia sebagai mesin kondisi kondisi aplikasi gaya arsitektur REST.
sumber
Saya biasanya lebih suka sesuatu yang sedikit lebih sederhana, seperti
activate
/deactivate
sub-sumber daya (dihubungkan denganLink
header denganrel=service
).atau
Untuk konsumen, antarmuka ini sangat sederhana, dan mengikuti prinsip REST tanpa menghalangi Anda dalam membuat konsep "aktivasi" sebagai sumber daya individual.
sumber
Salah satu opsi yang memungkinkan untuk menerapkan perilaku tersebut adalah
Dan jelas, jika seseorang perlu menonaktifkannya,
PUT
akanDeactivated
berstatus di JSON.Dalam hal perlunya aktivasi / penonaktifan massal,
PATCH
dapat melangkah ke dalam game (bukan untuk grup yang tepat, tetapi untukgroups
sumber daya:Secara umum ini adalah ide yang disarankan oleh @Andrew Dobrowolski, tetapi dengan sedikit perubahan dalam realisasi yang tepat.
sumber