RESTFul: การดำเนินการเปลี่ยนสถานะ

ฉันกำลังวางแผนที่จะสร้าง RESTfull API แต่มีคำถามสถาปัตยกรรมที่สร้างปัญหาในหัวของฉัน การเพิ่มตรรกะธุรกิจแบ็กเอนด์ให้กับลูกค้าเป็นตัวเลือกที่ฉันต้องการหลีกเลี่ยงเนื่องจากการอัปเดตแพลตฟอร์มไคลเอนต์หลายแห่งนั้นยากที่จะรักษาในเวลาจริงเมื่อตรรกะธุรกิจสามารถเปลี่ยนแปลงได้อย่างรวดเร็ว

ช่วยบอกว่าเรามีบทความเป็นทรัพยากร (api / บทความ) เราควรใช้การดำเนินการเช่นเผยแพร่, ไม่เผยแพร่, เปิดใช้งานหรือปิดการใช้งานและอื่น ๆ แต่พยายามที่จะทำให้มันง่ายที่สุด?

1) เราควรใช้ api / article / {id} / {action} เนื่องจากตรรกะส่วนแบ็คเอนด์จำนวนมากสามารถเกิดขึ้นที่นั่นได้เช่นการผลักไปยังสถานที่ห่างไกลหรือเปลี่ยนคุณสมบัติหลายอย่าง อาจเป็นสิ่งที่ยากที่สุดที่นี่คือเราจำเป็นต้องส่งข้อมูลบทความทั้งหมดกลับไปที่ API เพื่ออัปเดตและไม่สามารถใช้งานได้หลายผู้ใช้ ตัวอย่างเช่นผู้แก้ไขสามารถส่งข้อมูลที่เก่ากว่า 5 วินาทีและเขียนทับการแก้ไขที่นักข่าวคนอื่นเพิ่งทำเมื่อ 2 วินาทีที่ผ่านมาและไม่มีทางที่ฉันจะอธิบายให้ลูกค้าฟังได้เนื่องจากผู้เผยแพร่บทความไม่ได้เชื่อมต่อกับการปรับปรุงเนื้อหา

2) การสร้างทรัพยากรใหม่อาจเป็นตัวเลือก api / article- {action} / id แต่จากนั้นทรัพยากรที่ส่งคืนจะไม่เป็น article- {action} แต่บทความที่ฉันไม่แน่ใจว่าเหมาะสมหรือไม่ นอกจากนี้ในบทความคลาสโค้ดฝั่งเซิร์ฟเวอร์ก็จัดการ actuall บนทรัพยากรทั้งสองและฉันไม่แน่ใจว่าสิ่งนี้ขัดกับแนวคิด RESTfull หรือไม่

ข้อเสนอแนะใด ๆ ยินดี ..

ฉันพบแนวทางปฏิบัติที่อธิบายไว้ที่นี่เพื่อเป็นประโยชน์:

แล้วการกระทำที่ไม่เข้ากับโลกของการปฏิบัติการ CRUD ล่ะ?

นี่คือสิ่งที่สามารถคลุมเครือ มีหลายวิธี:

1. จัดโครงสร้างการดำเนินการให้ปรากฏเหมือนเขตข้อมูลของทรัพยากร ใช้งานได้หากการดำเนินการไม่ใช้พารามิเตอร์ ตัวอย่างเช่นการ ดำเนินการเปิดใช้งานสามารถแมปไปยังactivatedฟิลด์บูลีนและอัปเดตผ่าน PATCH ไปยังทรัพยากร
2. ปฏิบัติต่อมันเหมือนเป็นทรัพยากรย่อยด้วยหลักการ RESTful ยกตัวอย่างเช่น GitHub ของ API จะช่วยให้คุณดาวเค้าด้วย PUT /gists/:id/starและยกเลิกการติดดาวDELETE /gists/:id/starด้วย
3. บางครั้งคุณไม่มีทางที่จะแมปแอคชั่นกับโครงสร้าง RESTful ที่สมเหตุสมผล ตัวอย่างเช่นการค้นหาหลายทรัพยากรไม่สมเหตุสมผลที่จะนำไปใช้กับจุดสิ้นสุดของทรัพยากรที่เฉพาะเจาะจง ในกรณีนี้ /searchจะเหมาะสมที่สุดแม้ว่าจะไม่ใช่ทรัพยากร ไม่เป็นไร - ทำสิ่งที่ถูกต้องจากมุมมองของผู้ใช้ API และตรวจสอบให้แน่ใจว่ามีการจัดทำเอกสารอย่างชัดเจนเพื่อหลีกเลี่ยงความสับสน

การดำเนินการที่ทำให้เกิดการเปลี่ยนแปลงสถานะและพฤติกรรมที่สำคัญในฝั่งเซิร์ฟเวอร์เช่นการกระทำ "เผยแพร่" ที่คุณอธิบายนั้นยากที่จะสร้างแบบจำลองอย่างชัดเจนใน REST ทางออกที่ฉันมักจะเห็นก็คือการผลักดันพฤติกรรมที่ซับซ้อนเช่นนั้นโดยนัยผ่านข้อมูล

พิจารณาสั่งซื้อสินค้าผ่าน REST API ที่เปิดเผยโดยผู้ขายออนไลน์ การสั่งซื้อเป็นการดำเนินการที่ซับซ้อน ผลิตภัณฑ์จำนวนมากจะได้รับการบรรจุและจัดส่งบัญชีของคุณจะถูกเรียกเก็บเงินและคุณจะได้รับใบเสร็จ คุณสามารถยกเลิกคำสั่งซื้อของคุณในระยะเวลาที่ จำกัด และมีการรับประกันคืนเงินเต็มจำนวนซึ่งช่วยให้คุณสามารถส่งคืนสินค้าเพื่อขอเงินคืน

แทนที่จะเป็นการดำเนินการซื้อที่ซับซ้อน API ดังกล่าวอาจอนุญาตให้คุณสร้างทรัพยากรใหม่คำสั่งซื้อ ในตอนแรกคุณสามารถทำการแก้ไขใด ๆ ที่คุณต้องการ: เพิ่มหรือลบผลิตภัณฑ์เปลี่ยนที่อยู่จัดส่งเลือกตัวเลือกการชำระเงินอื่นหรือยกเลิกคำสั่งซื้อของคุณทั้งหมด คุณสามารถทำสิ่งเหล่านี้ได้เพราะคุณยังไม่ได้ซื้ออะไรเลยคุณแค่จัดการข้อมูลบางอย่างบนเซิร์ฟเวอร์

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

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

เราจำเป็นต้องส่งข้อมูลบทความทั้งหมดกลับไปที่ API เพื่ออัปเดตและไม่สามารถใช้งานผู้ใช้หลายคนได้ ตัวอย่างเช่นผู้แก้ไขสามารถส่งข้อมูลที่เก่ากว่า 5 วินาทีและเขียนทับการแก้ไขที่นักข่าวคนอื่นเพิ่งทำเมื่อ 2 วินาทีที่แล้วและไม่มีทางที่ฉันจะอธิบายให้ลูกค้าฟังได้เนื่องจากผู้เผยแพร่บทความไม่ได้เชื่อมต่อกับการปรับปรุงเนื้อหา

สิ่งนี้เป็นเรื่องที่ท้าทายไม่ว่าคุณจะทำอะไรมันเป็นปัญหาที่คล้ายกันมากกับการควบคุมแหล่งสัญญาณแบบกระจาย (Mercurial, git, ฯลฯ ) และวิธีแก้ปัญหาที่สะกดใน HTTP / ReST นั้นคล้ายกันเล็กน้อย

/articles/lunchเผื่อว่าคุณได้มีผู้ใช้สองคนอลิซและบ๊อบทั้งการทำงานใน (เพื่อความชัดเจนการตอบสนองจะเป็นแบบตัวหนา)

ประการแรกอลิซสร้างบทความ

PUT /articles/lunch HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic YWxpY2U6c2VjcmV0

Hey Bob, what do you want for lunch today?

301 Moved Permanently
Location: /articles/lunch/1 

เซิร์ฟเวอร์ไม่ได้สร้างทรัพยากรเพราะไม่มี "เวอร์ชั่น" แนบมากับคำขอ (สมมติว่าเป็นตัวระบุ/articles/{id}/{version}เพื่อทำการสร้างอลิซถูกเปลี่ยนเส้นทางไปยัง URL ของบทความ / เวอร์ชั่นที่เธอจะสร้างขึ้นผู้ใช้ของอลิซ ตัวแทนจะนำคำขอไปใช้ใหม่ตามที่อยู่ใหม่

PUT /articles/lunch/1 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic YWxpY2U6c2VjcmV0

Hey Bob, what do you want for lunch today?

201 Created

และตอนนี้บทความได้ถูกสร้างขึ้น ต่อไปบ๊อบดูที่บทความ:

GET /articles/lunch HTTP/1.1
Host: example.com
Authorization: Basic Ym9iOnBhc3N3b3Jk

301 Moved Permanently
Location: /articles/lunch/1 

Bob มองไปที่นั่น:

GET /articles/lunch/1 HTTP/1.1
Host: example.com
Authorization: Basic Ym9iOnBhc3N3b3Jk

200 Ok
Content-Type: text/plain

Hey Bob, what do you want for lunch today?

เขาตัดสินใจที่จะเพิ่มการเปลี่ยนแปลงของเขาเอง

PUT /articles/lunch/1 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic Ym9iOnBhc3N3b3Jk

Hey Bob, what do you want for lunch today?
Does pizza sound good to you, Alice?

301 Moved Permanently
Location: /articles/lunch/2

เช่นเดียวกับอลิซบ๊อบจะถูกนำไปที่ที่เขาจะสร้างเวอร์ชั่นใหม่

PUT /articles/lunch/2 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic Ym9iOnBhc3N3b3Jk

Hey Bob, what do you want for lunch today?
Does pizza sound good to you, Alice?

201 Created

ในที่สุดอลิซตัดสินใจว่าเธออยากจะเพิ่มบทความของเธอเอง:

PUT /articles/lunch/1 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic YWxpY2U6c2VjcmV0

Hey Bob, what do you want for lunch today?
I was thinking about getting Sushi.

409 Conflict
Location: /articles/lunch/3
Content-Type: text/diff

---/articles/lunch/2
+++/articles/lunch/3
@@ 1,2 1,2 @@
 Hey Bob, what do you want for lunch today?
-Does pizza sound good to you, Alice?
+I was thinking about getting Sushi.

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

การเปลี่ยนเส้นทางทั้งหมดนี้เกี่ยวข้องกับซีแมนทิกส์ของPUTซึ่งต้องการให้มีการสร้างทรัพยากรใหม่ตรงที่บรรทัดคำขอถาม สิ่งนี้สามารถบันทึกวงจรการร้องขอโดยใช้POSTแทนได้ แต่จากนั้นหมายเลขรุ่นจะต้องถูกเข้ารหัสในการร้องขอโดยเวทมนตร์อื่น ๆ ซึ่งดูเหมือนจะไม่ค่อยชัดเจนสำหรับฉันสำหรับวัตถุประสงค์ในการแสดงภาพประกอบ แต่อาจจะยังคงเป็นที่ต้องการใน API จริง เพื่อลดรอบคำขอ / การตอบกลับ

นี่คืออีกตัวอย่างหนึ่งที่ไม่เกี่ยวข้องกับเนื้อหาเอกสาร แต่มีอีกหลายอย่างที่เกี่ยวข้องกับสถานะชั่วคราว (ฉันค้นหาการกำหนดเวอร์ชัน - โดยทั่วไปแล้วแต่ละเวอร์ชันสามารถเป็นแหล่งข้อมูลใหม่ - เป็นปัญหาที่ง่าย)

สมมติว่าฉันต้องการให้บริการที่ใช้งานอยู่บนเครื่องผ่าน REST เพื่อให้สามารถหยุดทำงานเริ่มต้นเริ่มต้นใหม่และอื่น ๆ ได้

วิธี RESTful ที่สุดที่นี่คืออะไร? POST / service? command = restart ตัวอย่างเช่น หรือ POST / service / state ด้วยเนื้อความของ, พูด, 'running'?

มันเป็นการดีที่จะประมวลวิธีปฏิบัติที่ดีที่สุดที่นี่และ REST เป็นแนวทางที่ถูกต้องหรือไม่สถานการณ์ประเภทนี้

ประการที่สองสมมติว่าฉันต้องการผลักดันการกระทำบางอย่างจากบริการที่ไม่ส่งผลกระทบต่อสถานะของตัวเอง แต่จะกระตุ้นให้เกิดผลข้างเคียง ตัวอย่างเช่นบริการจดหมายที่ส่งรายงานที่สร้างขึ้นในเวลาที่โทรไปยังที่อยู่อีเมลจำนวนมาก

GET / report อาจเป็นวิธีหนึ่งในการรับสำเนารายงานด้วยตนเอง แต่ถ้าเราต้องการที่จะผลักดันไปยังฝั่งเซิร์ฟเวอร์ให้ดำเนินการเพิ่มเติมเช่นการส่งอีเมลตามที่ฉันพูดไว้ข้างต้น หรือเขียนไปยังฐานข้อมูล

กรณีเหล่านี้เต้นไปรอบ ๆ การแบ่งทรัพยากรและฉันเห็นวิธีจัดการกับพวกเขาในลักษณะที่มุ่งเน้นไปที่ REST แต่ตรงไปตรงมารู้สึกเหมือนเป็นแฮ็คสักหน่อยที่จะทำเช่นนั้น บางทีคำถามสำคัญคือ REST API ควรสนับสนุนผลข้างเคียงโดยทั่วไปหรือไม่

ส่วนที่เหลือเป็นข้อมูลเชิงและทรัพยากรดังกล่าวทำงานได้ดีที่สุดเป็น "สิ่ง" ไม่กระทำ ความหมายโดยนัยของวิธีการ http; GET, PUT, DELETE และอื่น ๆ ทำหน้าที่เพื่อเสริมสร้างการวางแนว แน่นอนโพสต์เป็นข้อยกเว้น

ทรัพยากรสามารถเป็นส่วนผสมของข้อมูลเช่น เนื้อหาบทความ; และข้อมูลเมตาคือ ตีพิมพ์, ล็อค, แก้ไข มีวิธีที่เป็นไปได้อื่น ๆ อีกมากมายในการแบ่งข้อมูล แต่คุณต้องดูว่าการไหลของข้อมูลจะเป็นอย่างไรก่อนเพื่อพิจารณาวิธีที่เหมาะสมที่สุด (ถ้ามี) ตัวอย่างเช่นอาจเป็นได้ว่าการแก้ไขควรเป็นทรัพยากรของตนเองภายใต้บทความตามที่ TokenMacGuy แนะนำ

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

อย่าคิดว่าเป็นการจัดการสถานะของบทความโดยตรง คุณกำลังเปลี่ยนลำดับขอให้สร้างบทความแทน

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

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

ความเข้าใจที่สำคัญสำหรับฉันคือการรับรู้คำอุปมาการเปลี่ยนแปลงนี้เป็นเพียงอีกวิธีหนึ่งในการอธิบายการเขียนโปรแกรมเชิงวัตถุ แทนที่จะเรียกใช้ทรัพยากรเราจึงเรียกอ็อบเจกต์ แทนที่จะเรียกคำสั่งเปลี่ยนเราเรียกพวกเขาว่าข้อความ วิธีหนึ่งในการส่งข้อความจาก A ถึง B ใน OO คือการเรียก A บน B วิธีอื่นโดยเฉพาะอย่างยิ่งเมื่อ A และ B อยู่ในคอมพิวเตอร์ที่แตกต่างกันคือ A สร้างวัตถุใหม่ M และ ส่งไปที่ B. REST เพียงทำพิธีการอย่างเป็นทางการ

หากฉันเข้าใจคุณอย่างถูกต้องฉันคิดว่าสิ่งที่คุณมีคือปัญหาการกำหนด 'กฎทางธุรกิจ' มากกว่าปัญหาทางเทคนิค

ความจริงที่ว่าบทความที่สามารถเขียนทับสามารถแก้ไขได้โดยการแนะนำระดับการอนุญาตที่ผู้ใช้ระดับสูงสามารถแทนที่รุ่นของผู้ใช้รุ่นจูเนียร์นอกจากนี้โดยการแนะนำรุ่นเช่นเดียวกับคอลัมน์เพื่อจับภาพสถานะของบทความ (เช่น 'ในการพัฒนา', 'สุดท้าย' ฯลฯ ) คุณสามารถเอาชนะสิ่งนี้ได้ นอกจากนี้คุณยังสามารถให้ผู้ใช้สามารถเลือกรุ่นที่กำหนดได้ทั้งจากเวลาในการส่งและหมายเลขรุ่น

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