Menerapkan pola perintah di API RESTful

Saya sedang dalam proses mendesain API HTTP, semoga membuatnya setenang mungkin.

Ada beberapa tindakan yang fungsionalitasnya tersebar di beberapa sumber daya, dan terkadang perlu dibatalkan.

Saya berpikir sendiri, ini terdengar seperti pola perintah, tetapi bagaimana saya bisa memodelkannya menjadi sumber daya?

Saya akan memperkenalkan sumber daya baru bernama XXAction, seperti DepositAction, yang akan dibuat melalui sesuatu seperti ini

POST /card/{card-id}/account/{account-id}/Deposit
AmountToDeposit=100, different parameters...

ini sebenarnya akan membuat DepositAction baru dan mengaktifkan metode Do / Execute-nya. Dalam hal ini, mengembalikan status HTTP Dibuat 201 berarti tindakan telah berhasil dilaksanakan.

Nanti jika klien ingin melihat detail tindakan yang dia bisa

GET /action/{action-id}

Pembaruan / PUT saya kira harus diblokir, karena tidak relevan di sini.

Dan untuk membatalkan aksinya, saya berpikir untuk menggunakan

DELETE /action/{action-id}

yang sebenarnya akan memanggil metode Undo objek yang relevan, dan ubah statusnya.

Katakanlah saya senang dengan hanya satu Do-Undo, saya tidak perlu Redo.

Apakah pendekatan ini oke?

Apakah ada jebakan, alasan untuk tidak menggunakannya?

Apakah ini dipahami dari POV klien?

Anda menambahkan lapisan abstraksi yang membingungkan

API Anda dimulai dengan sangat bersih dan sederhana. HTTP POST membuat sumber daya Deposit baru dengan parameter yang diberikan. Kemudian Anda keluar dari jalur dengan memperkenalkan gagasan "tindakan" yang merupakan detail implementasi daripada bagian inti dari API.

Sebagai alternatif pertimbangkan percakapan HTTP ini ...

POST / kartu / {card-id} / akun / {akun-id} / Setoran

AmountToDeposit = 100, parameter berbeda ...

201 DICIPTAKAN

Lokasi = / kartu / 123 / akun / 456 / Setoran / 789

Sekarang Anda ingin membatalkan operasi ini (secara teknis ini tidak boleh diizinkan dalam sistem akuntansi yang seimbang tapi apa hei):

HAPUS / kartu / 123 / akun / 456 / Setoran / 789

204 TANPA KONTEN

Konsumen API tahu bahwa mereka berurusan dengan sumber daya Deposit dan dapat menentukan operasi apa yang diizinkan di atasnya (biasanya melalui OPSI dalam HTTP).

Meskipun implementasi operasi penghapusan dilakukan melalui "tindakan" hari ini, tidak ada jaminan bahwa ketika Anda memigrasi sistem ini dari, katakanlah, C # ke Haskell dan pertahankan ujung depan bahwa konsep sekunder "tindakan" akan terus menambah nilai. , sedangkan konsep utama dari Deposit tentu saja.

Edit untuk mencakup alternatif untuk HAPUS dan Setoran

Untuk menghindari operasi penghapusan, tetapi masih secara efektif menghapus Setoran Anda harus melakukan yang berikut (menggunakan Transaksi generik untuk memungkinkan Setoran dan Penarikan):

POST / kartu / {card-id} / akun / {akun-id} / Transaksi

Jumlah = -100 , parameter berbeda ...

201 DICIPTAKAN

Lokasi = / kartu / 123 / akun / 456 / Transasi / 790

Sumber daya Transaksi baru dibuat yang memiliki jumlah yang persis berlawanan (-100). Ini memiliki efek menyeimbangkan akun kembali ke 0, meniadakan Transaksi asli.

Anda mungkin mempertimbangkan untuk membuat titik akhir "utilitas"

POST / kartu / {card-id} / akun / {akun-id} / Transaksi / 789 / Undo <- BUR!

untuk mendapatkan efek yang sama. Namun, ini mematahkan semantik URI sebagai pengidentifikasi dengan memperkenalkan kata kerja. Anda lebih baik tetap berpegang pada kata benda di pengidentifikasi dan menjaga operasi dibatasi ke kata kerja HTTP. Dengan begitu Anda dapat dengan mudah membuat permalink dari pengidentifikasi dan menggunakannya untuk GET dan sebagainya.

Alasan utama untuk keberadaan REST adalah ketahanan terhadap kesalahan jaringan. Untuk itu semua operasi harus idempoten .

Pendekatan dasar tampaknya masuk akal, tetapi cara Anda menggambarkan DepositActionpenciptaan tidak terdengar idempoten, yang harus diperbaiki. Dengan meminta klien memberikan ID unik yang akan digunakan untuk mendeteksi permintaan duplikat. Jadi ciptaan akan berubah menjadi

PUT /card/{card-id}/account/{account-id}/Deposit/{action-id}
AmountToDeposit=100, different parameters...

Jika PUT lain untuk URL yang sama dibuat dengan konten yang sama seperti sebelumnya, responsnya tetap harus 201 createdjika kontennya sama dan kesalahan jika kontennya berbeda. Ini memungkinkan klien untuk mengirimkan kembali permintaan ketika gagal, karena klien tidak dapat memastikan apakah permintaan atau responsnya hilang.

Lebih masuk akal untuk menggunakan PUT, karena itu hanya menulis sumber daya dan idempoten, tetapi menggunakan POST tidak akan benar-benar menyebabkan masalah juga.

Untuk melihat rincian transaksi, klien akan GETmemiliki URL yang sama, yaitu

GET /card/{card-id}/account/{account-id}/Deposit/{action-id}

dan untuk membatalkannya, ia dapat HAPUS. Tetapi jika itu benar-benar ada hubungannya dengan uang seperti yang disarankan sampel, saya akan menyarankan PUTting dengan menambahkan "dibatalkan" bendera sebagai gantinya untuk akuntabilitas (bahwa masih ada jejak transaksi dibuat dan dibatalkan).

Sekarang Anda harus memilih metode untuk membuat id unik. Anda memiliki beberapa opsi:

1. Keluarkan awalan khusus klien sebelumnya dalam pertukaran yang harus disertakan.
2. Tambahkan permintaan POST khusus untuk mendapatkan ID unik kosong dari server. Permintaan ini tidak harus idempoten (dan tidak bisa, sungguh), karena ID yang tidak digunakan tidak benar-benar menyebabkan masalah.
3. Cukup gunakan UUID. Semua orang menggunakannya dan tampaknya tidak ada masalah dengan yang berbasis MAC maupun yang acak.