'การค้นพบ' ใน REST API ต้องการอะไรเมื่อลูกค้ายังไม่ก้าวหน้าพอที่จะใช้มันได้

การพูดคุยที่หลากหลายที่ฉันได้ดูและแบบฝึกหัดที่ฉันสแกนบน REST ดูเหมือนจะเน้นสิ่งที่เรียกว่า 'การค้นพบ' สำหรับความเข้าใจที่ จำกัด ของฉันคำศัพท์น่าจะหมายถึงว่าลูกค้าควรจะสามารถไปhttp://URL- และรับรายการสิ่งที่สามารถทำได้โดยอัตโนมัติ

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

ดังนั้นจุดของการค้นพบคืออะไรเมื่อรหัสลูกค้าที่เข้าถึง URL ที่ค้นพบดังกล่าวไม่สามารถทำอะไรกับมันได้เว้นแต่ผู้พัฒนามนุษย์ของลูกค้าจะทำการทดลองจริง ๆ กับทรัพยากรที่นำเสนอ? ดูเหมือนว่าสิ่งเดียวกันกับการกำหนดชุดของฟังก์ชั่นที่มีอยู่ในคู่มือเอกสารเพียงจากทิศทางที่แตกต่างและจริง ๆ แล้วเกี่ยวข้องกับการทำงานมากขึ้นสำหรับนักพัฒนา เหตุใดแนวทางที่สองนี้ของการกำหนดล่วงหน้าสิ่งที่สามารถทำได้ในเอกสารภายนอกกับทรัพยากร REST ที่แท้จริงถือว่าต่ำกว่า

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

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

ตัวอย่างเช่น Jenkins (เซิร์ฟเวอร์ CI) มีอินเทอร์เฟซคล้าย REST ไปที่หน้าใดก็ได้โพสต์ URL ด้วย "/ api" และคุณจะได้รับหน้าที่อธิบายทุกสิ่งที่คุณทำได้ มันทำให้การเรียนรู้ API เล็กน้อย ตัวอย่างเช่นhttp://ci.jruby.orgจะนำคุณไปยังเซิร์ฟเวอร์ jenkins สำหรับ jruby และhttp://ci.jruby.org/apiจะนำคุณไปยัง api สำหรับหน้าเฉพาะนั้น

เมื่อไม่นานมานี้ฉันมีความสุขที่ได้ทำงานกับ API ที่มีเอกสารที่เข้าใจยากมาก

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

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

หมายเหตุ: ฉันไม่มีความเชี่ยวชาญในเรื่องนี้ แต่ฉันได้ผ่านกระบวนการที่คล้ายกันในการพยายามปรับความแตกต่างของการตีความ "REST" ของผู้คนเมื่อสองสามปีก่อนและนี่คือสิ่งที่ฉันได้มาจากการมองเข้าไปที่ เวลา.

เพื่อความเข้าใจของฉันสิ่งนี้เกิดขึ้นจากHypermediaของ Roy Fielding ในฐานะ Engine of Application Stateหรือที่รู้จักกันในนาม "HATEOAS" ซึ่งต่อมาได้กลายเป็นตัวกำหนดความคิดของ "semantic web"

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

หากคุณเพียงแค่ใช้ "REST" สำหรับ URL ที่สวยที่แมปกับการดำเนินงาน CRUD ที่ผู้บริโภคต้องมีความรู้ก่อนและโทรตามสัญญาที่รู้จักกันดี Roy Fielding จะเห็นว่ามันไม่สงบจริง ๆ

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