การนำรูปแบบคำสั่งไปใช้ใน RESTful API

ฉันอยู่ในขั้นตอนการออกแบบ HTTP API หวังว่าจะทำให้ RESTful ที่สุดเท่าที่จะทำได้

มีการกระทำบางอย่างที่ฟังก์ชันการทำงานกระจายไปทั่วทรัพยากรบางอย่างและบางครั้งจำเป็นต้องเลิกทำ

ฉันคิดกับตัวเองเสียงนี้ดูเหมือนรูปแบบคำสั่ง แต่ฉันจะสร้างแบบจำลองเป็นทรัพยากรได้อย่างไร

ฉันจะแนะนำทรัพยากรใหม่ชื่อ XXAction เช่น DepositAction ซึ่งจะถูกสร้างขึ้นผ่านบางสิ่งเช่นนี้

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

สิ่งนี้จะสร้าง DepositAction ใหม่และเปิดใช้งานวิธีการ Do / Execute ในกรณีนี้การส่งคืนสถานะ HTTP ที่สร้าง 201 หมายถึงการดำเนินการถูกดำเนินการสำเร็จ

หลังจากนั้นหากลูกค้าต้องการดูรายละเอียดการกระทำที่เขาสามารถทำได้

GET /action/{action-id}

ควรปิดกั้นการอัปเดต / วางเพราะฉันไม่เกี่ยวข้องที่นี่

และเพื่อเลิกทำการกระทำฉันคิดถึงการใช้

DELETE /action/{action-id}

ซึ่งจริงๆแล้วจะเรียกวิธีการเลิกทำของวัตถุที่เกี่ยวข้องและเปลี่ยนสถานะเป็น

สมมติว่าฉันมีความสุขกับสิ่งเดียวที่ต้องเลิกทำฉันไม่จำเป็นต้องทำซ้ำ

วิธีนี้ใช้ได้หรือไม่

มีข้อผิดพลาดใด ๆ เหตุผลที่จะไม่ใช้มัน?

สิ่งนี้เป็นที่เข้าใจจาก POV ของลูกค้าหรือไม่

คุณกำลังเพิ่มเลเยอร์ของนามธรรมที่ทำให้เกิดความสับสน

API ของคุณเริ่มต้นอย่างสะอาดและเรียบง่าย HTTP POST สร้างทรัพยากรการฝากใหม่ที่มีพารามิเตอร์ที่กำหนด จากนั้นคุณก็ลงจากรางโดยแนะนำแนวคิดของ "การกระทำ" ที่มีรายละเอียดการนำไปปฏิบัติแทนที่จะเป็นส่วนหลักของ API

อีกทางเลือกหนึ่งพิจารณาการสนทนา HTTP นี้ ...

POST / card / {card-id} / บัญชี / {account-id} / เงินฝาก

AmountToDeposit = 100 พารามิเตอร์ต่าง ๆ ...

201 สร้างแล้ว

สถานที่ตั้ง = / บัตร / 123 / บัญชี / 456 / เงินฝาก / 789

ตอนนี้คุณต้องการยกเลิกการดำเนินการนี้ (ในทางเทคนิคแล้วสิ่งนี้ไม่ควรได้รับอนุญาตในระบบบัญชีที่สมดุล แต่มันคืออะไร):

ลบ / การ์ด / 123 / บัญชี / 456 / ฝาก / 789

204 ไม่มีเนื้อหา

ผู้ใช้ API รู้ว่าพวกเขากำลังจัดการกับทรัพยากรการฝากเงินและสามารถกำหนดได้ว่าจะอนุญาตให้ดำเนินการใดได้บ้าง (โดยทั่วไปผ่านทาง OPTIONS ใน HTTP)

แม้ว่าการดำเนินการลบจะดำเนินการผ่าน "การกระทำ" ในปัจจุบันไม่มีการรับประกันว่าเมื่อคุณย้ายระบบนี้จากพูดว่า C # ถึง Haskell และรักษาส่วนหน้าว่าแนวคิดรองของ "การกระทำ" จะยังคงเพิ่มมูลค่าต่อไป ในขณะที่แนวคิดหลักของการฝากเงินไม่แน่นอน

แก้ไขเพื่อให้ครอบคลุมทางเลือกในการลบและการฝากเงิน

เพื่อหลีกเลี่ยงการลบ แต่ยังคงมีประสิทธิภาพในการฝากเงินคุณควรทำสิ่งต่อไปนี้ (ใช้ธุรกรรมทั่วไปเพื่ออนุญาตให้ฝากและถอนเงิน):

POST / card / {card-id} / บัญชี / {account-id} / ทรานแซคชัน

จำนวน = -100พารามิเตอร์ต่าง ๆ ...

201 สร้างแล้ว

สถานที่ตั้ง = / บัตร / 123 / บัญชี / 456 / Transation / 790

ทรัพยากรธุรกรรมใหม่ถูกสร้างขึ้นซึ่งมีจำนวนตรงข้าม (-100) นี่คือผลกระทบของการปรับสมดุลบัญชีกลับเป็น 0 โดยไม่สนใจธุรกรรมเดิม

คุณอาจพิจารณาสร้างจุดปลาย "ยูทิลิตี้" เช่น

POST / card / {card-id} / บัญชี / {account-id} / Transaction / 789 / Undo <- BAD!

เพื่อให้ได้ผลเช่นเดียวกัน อย่างไรก็ตามสิ่งนี้จะแบ่งซีแมนทิกส์ของ URI ว่าเป็นตัวระบุโดยการใช้คำกริยา คุณดีกว่าไปเกาะติดกับคำนามในตัวระบุและทำให้การดำเนินการถูก จำกัด กับกริยา HTTP ด้วยวิธีนี้คุณสามารถสร้างลิงก์ได้อย่างง่ายดายจากตัวระบุและใช้สำหรับ GET และอื่น ๆ

เหตุผลหลักสำหรับการมีอยู่ของ REST นั้นมีความยืดหยุ่นต่อข้อผิดพลาดของเครือข่าย ที่จบการดำเนินงานทั้งหมดควรจะidempotent

วิธีการพื้นฐานดูเหมือนสมเหตุสมผล แต่วิธีที่คุณอธิบายการDepositActionสร้างไม่ได้ฟังว่าเป็น idempotent ซึ่งควรได้รับการแก้ไข โดยให้ลูกค้าให้ ID ที่ไม่ซ้ำที่จะใช้ในการตรวจสอบคำขอที่ซ้ำกัน ดังนั้นการสร้างจะเปลี่ยนเป็น

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

หากใส่ PUT อื่นไปยัง URL เดียวกันด้วยเนื้อหาเดียวกันกับก่อนหน้านี้การตอบสนองควรจะยังคงอยู่201 createdถ้าเนื้อหาเหมือนกันและมีข้อผิดพลาดหากเนื้อหานั้นแตกต่าง สิ่งนี้จะช่วยให้ลูกค้าสามารถส่งคำร้องขอใหม่เมื่อล้มเหลวเนื่องจากลูกค้าไม่สามารถบอกได้ว่าคำขอหรือการตอบสนองนั้นหายไปหรือไม่

มันสมเหตุสมผลมากกว่าที่จะใช้ PUT เพราะมันเพิ่งเขียนทรัพยากรและ idempotent แต่การใช้ POST จะไม่ทำให้เกิดปัญหาใด ๆ

หากต้องการดูรายละเอียดธุรกรรมลูกค้าจะGETใช้ URL เดียวกันคือ

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

และเมื่อต้องการเลิกทำมันสามารถลบได้ แต่ถ้ามันมีอะไรเกี่ยวข้องกับเงินจริงตามตัวอย่างแนะนำผมแนะนำให้ใส่ด้วยการเพิ่มค่าสถานะ "ยกเลิก" แทนเพื่อความรับผิดชอบ (ซึ่งยังคงมีร่องรอยของธุรกรรมที่สร้างและยกเลิก)

ตอนนี้คุณต้องเลือกวิธีการสร้าง id ที่ไม่ซ้ำกัน คุณมีหลายทางเลือก:

1. ออกคำนำหน้าเฉพาะลูกค้าก่อนหน้านี้ในการแลกเปลี่ยนที่จะต้องรวม
2. เพิ่มคำขอ POST พิเศษเพื่อรับ ID เฉพาะที่ไม่ซ้ำกันจากเซิร์ฟเวอร์ คำขอนี้ไม่จำเป็นต้องเป็น idempotent (และไม่สามารถทำได้จริง ๆ ) เพราะ ID ที่ไม่ได้ใช้จะไม่ทำให้เกิดปัญหาใด ๆ
3. เพียงใช้ UUID ทุกคนใช้พวกเขาและดูเหมือนว่าไม่มีใครมีปัญหาใด ๆ กับทั้งที่ใช้ MAC หรือแบบสุ่ม