Pertanyaan REST action dan pertimbangan desain URL API


Saya sedang membangun sistem manajemen persediaan dan saya sibuk merancang (memikirkan) API dan implementasi REST saya.

Saya memiliki sumber daya berikut dan pada sumber daya Anda dapat melakukan banyak tindakan / operasi. Setiap operasi akan memodifikasi sumber daya dan dalam beberapa kasus membuat sumber daya baru dan juga membuat sejarah atau transaksi.

Saya mencari beberapa masukan dari para ahli terkait dengan kegunaan dan penerimaan dalam hal desain URL dan sumber daya. Para gotha ​​dan contoh-contoh dunia nyata, setiap pendapat atau kritik menyambut.

Kekhawatiran saya adalah bahwa seluruh aplikasi mungkin berkembang di sekitar satu sumber daya besar ini? Backend stack saya adalah C # dan kerangka servicestack dan untuk frontend saya akan menggunakan HTML dan AngularJS. Bukannya itu membuat perbedaan.

Skenario 1. Operasi yang tipikal adalah:

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /inventory/{id}/pick
PUT  /inventory/{id}/receive
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /inventory/{id}/transfer
POST /inventory/{id}/return
POST /inventory/{id}/adjustment


{
  "userID": "",       //who is doing the actions (all)
  "tolocationID": "", //new location for inventory (move/takeon/pick/receive/transfer/return)
  "qty": "",          //qty (pick/receive/takeon/transfer/return)
  "comment": "",      //optional for transaction (all)
  "serial": "",       //(takeon/receive)
  "batch": "",        //(takeon/receive)
  "expirydate": "",   //(takeon/receive)
  "itemCode": "",     //(takeon/receive)
  "documentID": "",   //(pick/receive/return/transfer)
  "reference" :"",    //(all)
  "UOM" :"",          //(all)
  "reference" :"",    //(all)
}

Apakah ini dapat diterima dalam hal standar. Pendekatan lain mungkin.

Skenario 2.

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /document/{id}/pick     //**document**
PUT  /document/{id}/receive  //**document**
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /document/{id}/transfer  //**document**
POST /document/{id}/return    //**document**
POST /inventory/{id}/adjustment

dan kemudian mengubah sumber daya.

Skenario 3. menurut saya salah

POST /transaction/move/{...}
POST /transaction/scrap/{...}
PUT  /transaction/takeon/{...}
POST /transaction/pick/{...}  
PUT  /transaction/receive/{...} 
POST /transaction/hold/{...}
POST /transaction/release/{...}
POST /transaction/transfer/{...}  
POST /transaction/return/{...}
POST /transaction/adjustment/{...}

Ada komentar yang diterima, tidak mencari jawaban tetapi lebih banyak saran tentang pertimbangan desain?

Terima kasih telah meluangkan waktu membaca entri ini!


32
2017-08-13 13:39


asal


Jawaban:


Saya memiliki sumber daya berikut dan sumber daya yang dapat Anda lakukan   banyak tindakan / operasi. Setiap operasi akan memodifikasi sumber daya dan   dalam beberapa kasus membuat sumber daya baru dan juga membuat sejarah atau   transaksi.

Mendasar ke skema arsitektur REST adalah gagasan menggunakan kata kerja HTTP sebagai satu-satunya kata kerja, dan tidak termasuk kata kerja dalam URL Anda. Dalam sepatu Anda, saya akan mempertimbangkan pengerjaan ulang sistem Anda untuk menghapus kata kerja. Sulit untuk menyarankan desain tanpa benar-benar mengetahui apa arti kata kerja, tetapi mungkin sesuatu yang lebih dekat ke:

GET /inventory/{id}
PUT /inventory/{id} -- update with new location 
PUT /inventory/{id} -- update with new status (scrapped)

dll. Itu pendekatan yang lebih TEPAT. Banyak dari tindakan ini terlihat seperti benar-benar hanya PUT yang memperbarui beberapa properti sumber daya, seperti lokasi, kuantitas, bidang komentar, dll. Dan mungkin scrap apakah DELETE? Sulit untuk diceritakan.

Pilihan lain adalah menggunakan POST, di mana badan mencakup instruksi untuk cara beroperasi pada item inventaris:

POST /inventory-transactions/{id}
{
    "action": "takeon",
    "newLocationId": 12345,
    ...
}

Ini memberi Anda banyak ketertelusuran, karena setiap operasi sekarang dapat dilacak sebagai sumber daya. Sisi bawahnya adalah banyak kerumitan di sekitar titik akhir.

Anda juga dapat memecah beberapa operasi "kata kerja" menjadi sumber daya:

POST /returned-inventory
{
    "inventoryId": 12345,
    "documentId": 67890,
    "comment": "Busted up",
    ...
}

Ini memungkinkan Anda dengan mudah melihat item inventaris berdasarkan statusnya, yang mungkin atau mungkin tidak membantu. Anda dapat, misalnya, menelepon GET /returned-inventory?documentId=67890 untuk mendapatkan kembali semua barang yang dikembalikan dari dokumen yang sama.

Semoga ada beberapa makanan untuk dipikirkan di sana. Benar-benar tidak akan mungkin bagi siapa pun untuk memberi tahu Anda hal yang "benar" untuk dilakukan tanpa mengetahui persyaratan bisnis Anda secara lebih terperinci.


30
2017-08-13 14:03



"Objek Istirahat", yang mendefinisikan API TEPAT, menyatakan bahwa tindakan itu valid.

Tindakan yang tersedia dapat ditemukan, diaktifkan / dinonaktifkan, dan dapat memberikan umpan balik 'alasan tidak sah'.

Actions are 'invoked' menggunakan GET (query), PUT (idempotent), atau POST (non idempotent)

Spesifikasi Objek Tenang (halaman C-125)


8
2017-12-24 01:08