มีแนวทางการตั้งชื่อสำหรับ REST API หรือไม่ [ปิด]

เมื่อสร้าง REST API จะมีแนวทางหรือมาตรฐาน defacto สำหรับการตั้งชื่อการประชุมภายใน API (เช่น: ส่วนประกอบพา ธ ปลายทางของ URL, พารามิเตอร์การสอบถาม) อูฐแคปประจำหรือขีดล่างหรือไม่? คนอื่น ๆ ?

ตัวอย่างเช่น:

api.service.com/helloWorld/userId/x

หรือ

api.service.com/hello_world/user_id/x

หมายเหตุ: นี่ไม่ใช่คำถามของการออกแบบ RESTful API แต่เป็นแนวทางการตั้งชื่อเพื่อใช้สำหรับส่วนประกอบของพา ธ ในที่สุดและ / หรือพารามิเตอร์สตริงการสืบค้นที่ใช้

แนวทางใดจะได้รับการชื่นชม

ฉันคิดว่าคุณควรหลีกเลี่ยงหมวกอูฐ บรรทัดฐานคือการใช้ตัวอักษรตัวพิมพ์เล็ก ฉันจะหลีกเลี่ยงการขีดเส้นใต้และใช้เครื่องหมายขีดกลางแทน

ดังนั้น URL ของคุณควรมีลักษณะเช่นนี้ (ไม่สนใจปัญหาการออกแบบตามที่คุณร้องขอ :-))

api.service.com/hello-world/user-id/x

REST API สำหรับDropbox , Twitter , Google Web ServicesและFacebookทั้งหมดใช้ขีดล่าง

ดู URI อย่างละเอียดเพื่อหาแหล่งข้อมูลบนเว็บแบบธรรมดา นั่นคือแม่แบบของคุณ คิดว่าต้นไม้ไดเรกทอรี ใช้ชื่อไฟล์และไดเรกทอรีแบบ Linux อย่างง่าย

HelloWorldไม่ใช่แหล่งข้อมูลที่ดีจริงๆ ดูเหมือนจะไม่เป็น "สิ่ง" มันอาจจะเป็น แต่มันก็ไม่เหมือนคำนามมาก A greetingคือสิ่งหนึ่ง

user-idอาจเป็นคำนามที่คุณกำลังเรียก อย่างไรก็ตามเป็นที่น่าสงสัยว่าผลลัพธ์ของคำขอของคุณเป็นเพียง user_id มีโอกาสมากที่ผลลัพธ์ของคำขอจะเป็นผู้ใช้ ดังนั้นuserเป็นคำนามที่คุณกำลังเรียก

www.example.com/greeting/user/x/

ทำให้รู้สึกถึงฉัน มุ่งเน้นไปที่การขอให้ส่วนที่เหลือของคุณขอวลีคำนาม - เส้นทางผ่านลำดับชั้น (หรืออนุกรมวิธานหรือไดเรกทอรี) ใช้คำนามที่ง่ายที่สุดที่เป็นไปได้หลีกเลี่ยงวลีคำนามถ้าเป็นไปได้

โดยทั่วไปวลีคำนามประสมมักจะหมายถึงขั้นตอนอื่นในลำดับชั้นของคุณ ดังนั้นคุณจึงไม่ต้องและ/hello-world/user/ /hello-universe/user/คุณมีและ/hello/world/user/ hello/universe/user/หรืออาจจะเป็นและ/world/hello/user//universe/hello/user/

ประเด็นคือเพื่อให้เส้นทางการนำทางในหมู่ทรัพยากร

'รหัสผู้ใช้' เป็นวิธีที่ผิดทั้งหมด คำกริยา (HTTP วิธีการ) และวิธีการของคำนามคือสิ่งที่รอยฟีลดิงหมายสำหรับสถาปัตยกรรม REST คำนามมีดังนี้:

1. เก็บของสิ่งที่
2. สิ่ง

แบบแผนการตั้งชื่อที่ดีอย่างหนึ่งคือ:

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

โดยที่ {media_type} เป็นหนึ่งใน: json, xml, rss, pdf, png, แม้แต่ html

เป็นไปได้ที่จะแยกแยะคอลเลกชันโดยเพิ่ม 's' ที่ส่วนท้ายเช่น:

'users.json' *collection of things*
'user/id_value.json' *single thing*

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

ไม่ REST ไม่มีส่วนเกี่ยวข้องกับการตั้งชื่อ URI หากคุณรวมอนุสัญญาเหล่านี้ไว้เป็นส่วนหนึ่งของ API ของคุณนอกกรอบแทนที่จะผ่านไฮเปอร์เท็กซ์เท่านั้น API ของคุณจะไม่สงบ

สำหรับข้อมูลเพิ่มเติมดูที่http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

ชื่อโดเมนไม่ตรงตามตัวพิมพ์ใหญ่ - เล็ก แต่ส่วนที่เหลือของ URI สามารถเป็นได้ มันเป็นความผิดพลาดครั้งใหญ่ที่สมมติว่า URIs นั้นไม่ได้ตรงตามตัวพิมพ์ใหญ่ - เล็ก

ฉันมีรายการแนวทางที่http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.htmlซึ่งเราได้ใช้ในการผลิต แนวทางเป็นที่ถกเถียงกันอยู่เสมอ ... ฉันคิดว่าบางครั้งความมั่นคงมีความสำคัญมากกว่าการทำให้สมบูรณ์แบบ (หากมีสิ่งนั้น)

ฉันไม่คิดว่ากรณีอูฐเป็นปัญหาในตัวอย่างนั้น แต่ฉันคิดว่าหลักการตั้งชื่อ RESTful สำหรับตัวอย่างข้างต้นจะเป็น:

api.service.com/helloWorld/userId/x

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

หากคุณรับรองความถูกต้องของลูกค้าด้วย Oauth2 ฉันคิดว่าคุณจะต้องขีดเส้นใต้อย่างน้อยสองชื่อพารามิเตอร์ของคุณ:

• client_id
• client_secret

ฉันใช้ camelCase ใน REST API ของฉัน (ยังไม่เผยแพร่) ในขณะที่เขียนเอกสาร API ฉันคิดว่าจะเปลี่ยนทุกอย่างเป็น snake_case ดังนั้นฉันไม่ต้องอธิบายว่าทำไม Oauth params เป็น snake_case ในขณะที่ params อื่น ๆ ไม่ใช่

ดู: https://tools.ietf.org/html/rfc6749

ฉันจะบอกว่ามันจะดีกว่าที่จะใช้อักขระพิเศษน้อยที่สุดใน REST URL ข้อดีอย่างหนึ่งของ REST คือทำให้ "ส่วนต่อประสาน" สำหรับบริการอ่านง่าย กรณี Camel หรือ Pascal case น่าจะดีสำหรับชื่อทรัพยากร (ผู้ใช้หรือผู้ใช้) ฉันไม่คิดว่าจะมีมาตรฐานที่ยากใด ๆ รอบ ๆ REST

นอกจากนี้ฉันคิดว่า Gandalf นั้นถูกต้องปกติแล้วมันจะสะอาดกว่าใน REST ที่จะไม่ใช้พารามิเตอร์สตริงข้อความค้นหา แต่สร้างเส้นทางที่กำหนดทรัพยากรที่คุณต้องการจัดการแทน

http://api.example.com/HelloWorld/Users/12345/Order/3/etc