แบบแผน REST URI - ชื่อทรัพยากรเอกพจน์หรือพหูพจน์ขณะสร้าง

ฉันยังใหม่กับ REST และฉันสังเกตเห็นว่าในบริการ RESTful บางอย่างพวกเขาใช้ URI ทรัพยากรที่แตกต่างกันสำหรับการอัปเดต / รับ / ลบและสร้าง เช่น

• การสร้าง - การใช้/ ทรัพยากรด้วยวิธีการ POST (สังเกตพหูพจน์) ในบางสถานที่การใช้/ ทรัพยากร (เอกพจน์)
• ปรับปรุง - ใช้/ ทรัพยากร / 123ด้วยวิธีการ PUT
• รับ - การใช้/ ทรัพยากร / 123ด้วยวิธีการ GET

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

ข้อสมมติฐานของการใช้/resourcesคือมันแสดงถึงทรัพยากร "ทั้งหมด" หากคุณทำGET /resourcesคุณอาจจะกลับมาเก็บทั้งหมด โดย POSTing to /resourcesคุณกำลังเพิ่มลงในคอลเล็กชัน

อย่างไรก็ตามแต่ละทรัพยากรมีอยู่ที่ / ทรัพยากร หากคุณทำGET /resourceคุณอาจผิดพลาดเนื่องจากคำขอนี้ไม่สมเหตุสมผล แต่ก็/resource/123สมเหตุสมผลดี

ใช้/resourceแทนการ/resourcesจะคล้ายกับวิธีที่คุณจะทำเช่นนี้หากคุณกำลังทำงานกับกล่าวว่าระบบไฟล์และเก็บไฟล์และ/resourceเป็น directory "" กับบุคคล123, 456ไฟล์ในนั้น

ไม่ว่าจะถูกหรือผิดให้ไปกับสิ่งที่คุณชอบที่สุด

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

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

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

พหูพจน์

• ง่าย - URL ทั้งหมดเริ่มต้นด้วยคำนำหน้าเหมือนกัน
• Logical - orders/รับรายการดัชนีคำสั่งซื้อ
• มาตรฐาน - มาตรฐานที่ใช้กันอย่างแพร่หลายที่สุดตามด้วย API ของภาครัฐและเอกชนส่วนใหญ่

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

GET /resources - ส่งคืนรายการของรายการทรัพยากร

POST /resources - สร้างรายการทรัพยากรหนึ่งหรือหลายรายการ

PUT /resources - อัปเดตรายการทรัพยากรหนึ่งหรือหลายรายการ

PATCH /resources - อัปเดตรายการทรัพยากรหนึ่งหรือหลายรายการบางส่วน

DELETE /resources - ลบรายการทรัพยากรทั้งหมด

และสำหรับรายการทรัพยากรเดียว:

GET /resources/:id- ส่งคืนรายการทรัพยากรเฉพาะตาม:idพารามิเตอร์

POST /resources/:id - สร้างรายการทรัพยากรหนึ่งรายการพร้อมรหัสที่ระบุ (ต้องมีการตรวจสอบความถูกต้อง)

PUT /resources/:id - อัปเดตรายการทรัพยากรเฉพาะ

PATCH /resources/:id - อัปเดตรายการทรัพยากรเฉพาะบางส่วน

DELETE /resources/:id - ลบรายการทรัพยากรเฉพาะ

สำหรับผู้สนับสนุนเอกพจน์คิดแบบนี้: คุณจะขอคนorderและคาดหวังสิ่งหนึ่งหรือรายการสิ่งต่าง ๆ หรือไม่? ดังนั้นเหตุผลที่คุณจะคาดหวังการบริการที่จะกลับรายการของสิ่งที่เมื่อคุณพิมพ์/order?

เอกพจน์

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

เช่น CustomerAddress มากกว่า CustomerAddresses

พิจารณาทรัพยากรที่เกี่ยวข้องนี้

นี้สามารถอ่านได้มากขึ้นและตรรกะกว่า/order/12/orderdetail/12/orders/12/orderdetails/4

ตารางฐานข้อมูล

ทรัพยากรแสดงถึงเอนทิตีเช่นตารางฐานข้อมูล มันควรมีชื่อเอกพจน์เชิงตรรกะ นี่คือคำตอบของชื่อตาราง

การทำแผนที่ชั้น

ชั้นเรียนมีลักษณะเฉพาะตัวเสมอ เครื่องมือ ORM สร้างตารางที่มีชื่อเหมือนกับชื่อคลาส เมื่อมีการใช้เครื่องมือมากขึ้นเรื่อย ๆ ชื่อเอกพจน์กำลังกลายเป็นมาตรฐาน

อ่านเพิ่มเติมเกี่ยวกับDilemma ของผู้พัฒนา A REST API

ในขณะที่การปฏิบัติที่แพร่หลายมากที่สุดคือ apis RESTful ที่มีการใช้คำพหูพจน์เช่น/api/resources/123มีกรณีพิเศษหนึ่งกรณีที่ฉันพบการใช้ชื่อเอกพจน์ที่เหมาะสม / แสดงออกมากกว่าชื่อพหูพจน์ มันเป็นกรณีของความสัมพันธ์แบบหนึ่งต่อหนึ่ง โดยเฉพาะถ้ารายการเป้าหมายเป็นวัตถุค่า (ในกระบวนทัศน์การออกแบบที่ขับเคลื่อนด้วยโดเมน)

ให้เราสมมติว่าทุกทรัพยากรมีaccessLogตัวต่อตัวซึ่งสามารถจำลองเป็นวัตถุที่มีค่าเช่นไม่ใช่เอนทิตีดังนั้นจึงไม่มี ID /api/resources/123/accessLogมันอาจจะแสดงเป็น คำกริยาปกติ (POST, PUT, DELETE, GET) จะแสดงเจตนาอย่างเหมาะสมและความจริงที่ว่าความสัมพันธ์นั้นเป็นแบบตัวต่อตัว

ทำไมไม่ทำตามแนวโน้มที่แพร่หลายของชื่อตารางฐานข้อมูลโดยทั่วไปจะยอมรับรูปแบบเอกฐาน? เคยมาที่นั่นทำอย่างนั้น - ลองใช้ใหม่อีกครั้ง

ตารางการตั้งชื่อ Dilemma: ชื่อเอกพจน์และพหูพจน์

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

ดู http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

มีพหูพจน์ที่ผิดปกติหลายประเภท แต่สิ่งเหล่านี้พบได้บ่อยที่สุด:

คำนามประเภทการขึ้นรูปพหูพจน์ตัวอย่าง

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

จากมุมมองของผู้บริโภค API จุดสิ้นสุดควรคาดเดาได้

จะเป็นการดี ...

1. GET /resources ควรส่งคืนรายการทรัพยากร
2. GET /resource ควรส่งคืนรหัสสถานะ 400 ระดับ
3. GET /resources/id/{resourceId} ควรส่งคืนคอลเล็กชันที่มีหนึ่งรีซอร์ส
4. GET /resource/id/{resourceId} ควรส่งคืนวัตถุทรัพยากร
5. POST /resources แบทช์ควรสร้างทรัพยากร
6. POST /resource ควรสร้างทรัพยากร
7. PUT /resource ควรปรับปรุงวัตถุทรัพยากร
8. PATCH /resource ควรอัปเดตทรัพยากรโดยการโพสต์เฉพาะแอตทริบิวต์ที่เปลี่ยนแปลง
9. PATCH /resources ควรอัพเดททรัพยากรที่โพสต์คุณลักษณะเฉพาะที่มีการเปลี่ยนแปลง
10. DELETE /resourcesควรลบทรัพยากรทั้งหมด ล้อเล่น: รหัสสถานะ 400
11. DELETE /resource/id/{resourceId}

วิธีนี้เป็นวิธีที่ยืดหยุ่นและมีคุณลักษณะหลากหลาย แต่ยังใช้เวลานานในการพัฒนา ดังนั้นหากคุณกำลังรีบ (ซึ่งมักเป็นกรณีที่มีการพัฒนาซอฟต์แวร์) เพียงแค่ตั้งชื่อปลายทางresourceหรือรูปแบบพหูพจน์ของคุณresourcesคุณ ฉันชอบรูปแบบเอกพจน์เพราะมันให้คุณเลือกที่จะใคร่ครวญและประเมินผลทางโปรแกรมเนื่องจากรูปแบบพหูพจน์ไม่ทั้งหมดลงท้ายด้วย 's'

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

เกณฑ์การตัดสินใจบางอย่างอาจเป็น:

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

ดังนั้นมันขึ้นอยู่กับคุณ ทุกสิ่งที่คุณทำสอดคล้องกัน

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

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

ฉันชอบใช้รูปแบบเอกพจน์ทั้งความเรียบง่ายและความมั่นคง

ตัวอย่างเช่นพิจารณา URL ต่อไปนี้:

/ ลูกค้า / 1

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

ตัวอย่างอื่น:

/ อุปกรณ์ / 1

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

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

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

แต่ทรัพยากรบางอย่างไม่ได้ใช้รหัสในเส้นทางของพวกเขาเพราะมีเพียงรายการเดียวหรือผู้ใช้ไม่สามารถเข้าถึงมากกว่าหนึ่งรายการได้ดังนั้นรายการเหล่านั้นจึงไม่ใช่รายการ:

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

ด้วยการตั้งชื่อแบบแผนมักจะปลอดภัยที่จะพูดว่า "เพียงแค่เลือกหนึ่งตัวและติดมัน" ซึ่งเหมาะสมแล้ว

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

และภายในบริบทนั้นกฎทางภาษาศาสตร์จะทำให้คุณได้รับสิ่งต่อไปนี้เท่านั้น:

ไดเรกทอรีสามารถมีหลายไฟล์และ / หรือไดเรกทอรีย่อยและดังนั้นชื่อของมันควรอยู่ในรูปแบบพหูพจน์

และฉันชอบที่
ในทางกลับกัน - เป็นไดเรกทอรีของคุณคุณสามารถตั้งชื่อมันว่า "a-resource-or-multiple-resources" ถ้านั่นคือสิ่งที่คุณต้องการ นั่นไม่ใช่สิ่งสำคัญจริงๆ

สิ่งสำคัญคือถ้าคุณใส่ไฟล์ชื่อ "123" ภายใต้ไดเรกทอรีชื่อ "resourceS" (ส่งผลให้/resourceS/123) คุณจะไม่สามารถคาดหวังให้เข้าถึงไฟล์ผ่านทาง/resource/123คุณสามารถไม่ได้แล้วคาดว่าจะสามารถเข้าถึงได้ผ่าน

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

หมายเหตุ: ในทางเทคนิคคุณสามารถสร้าง "ลิงก์สัญลักษณ์" เพื่อให้/resources/123สามารถเข้าถึงได้ผ่านทาง/resource/123แต่ก่อนหน้านี้ยังคงมีอยู่!

มีลักษณะที่Google 's คู่มือการออกแบบ API: รายชื่อทรัพยากรสำหรับการใช้เวลาอีกต่อทรัพยากรการตั้งชื่อ

ในระยะสั้น:

• คอลเลกชันถูกตั้งชื่อด้วยพหูพจน์
• ทรัพยากรส่วนบุคคลมีชื่อด้วยสตริง

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

มันเป็นการอ่านที่คุ้มค่าหากคุณกำลังคิดเกี่ยวกับเรื่องนี้

การใช้พหูพจน์สำหรับวิธีการทั้งหมดนั้นมีประโยชน์มากกว่าอย่างน้อยในด้านเดียว: หากคุณกำลังพัฒนาและทดสอบ API ทรัพยากรโดยใช้บุรุษไปรษณีย์ (หรือเครื่องมือที่คล้ายกัน) คุณไม่จำเป็นต้องแก้ไข URI เมื่อเปลี่ยนจาก GET เป็น PUT เป็น POST เป็นต้น .

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

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

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

อนุสัญญาของฉันคือว่าแต่ละระดับความลึกใน URI อธิบายการโต้ตอบกับทรัพยากรหลักและ URI เต็มควรอธิบายสิ่งที่ถูกดึงโดยปริยาย

สมมติว่าเรามีรูปแบบดังต่อไปนี้

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

หากฉันต้องการจัดหาทรัพยากรที่อนุญาตให้ไคลเอนต์ได้รับผู้จัดการของเพื่อนโดยเฉพาะของผู้ใช้บางคนมันอาจมีลักษณะดังนี้:

GET /users/{id}/friends/{friendId}/manager

ต่อไปนี้เป็นตัวอย่างเพิ่มเติม:

• GET /users - แสดงรายการทรัพยากรผู้ใช้ในคอลเลกชันผู้ใช้ทั่วโลก
• POST /users - สร้างผู้ใช้ใหม่ในคอลเลกชันผู้ใช้ทั่วโลก
• GET /users/{id} - ดึงผู้ใช้เฉพาะจากการรวบรวมผู้ใช้ทั่วโลก
• GET /users/{id}/manager - รับผู้จัดการของผู้ใช้ที่เฉพาะเจาะจง
• GET /users/{id}/friends - รับรายชื่อเพื่อนของผู้ใช้
• GET /users/{id}/friends/{friendId} - รับเพื่อนเฉพาะของผู้ใช้
• LINK /users/{id}/friends - เพิ่มการเชื่อมโยงเพื่อนกับผู้ใช้รายนี้
• UNLINK /users/{id}/friends - ลบการเชื่อมโยงเพื่อนจากผู้ใช้รายนี้

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

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

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

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

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

ฉันไม่ชอบที่จะเห็น{id}ส่วนของ URL ที่ทับซ้อนกับทรัพยากรย่อยในฐานะidทางทฤษฎีอาจเป็นอะไรก็ได้และจะมีความกำกวม มันกำลังผสมแนวคิดที่แตกต่างกัน (ตัวระบุและชื่อทรัพยากรย่อย)

ปัญหาที่คล้ายกันมักจะเห็นในenumค่าคงที่หรือโฟลเดอร์โครงสร้างที่แนวคิดที่แตกต่างกันผสม (ตัวอย่างเช่นเมื่อคุณมีโฟลเดอร์Tigers, LionsและCheetahsแล้วยังโฟลเดอร์ที่เรียกว่าAnimalsอยู่ในระดับเดียวกัน - นี้ทำให้รู้สึกไม่เป็นหนึ่งเป็นส่วนหนึ่งของ อื่น ๆ )

โดยทั่วไปฉันคิดว่าส่วนสุดท้ายของปลายทางควรเป็นเอกเทศหากเกี่ยวข้องกับกิจการเดี่ยวในเวลาเดียวกันและเป็นพหูพจน์หากเกี่ยวข้องกับรายการของหน่วยงาน

ดังนั้นปลายทางที่จัดการกับผู้ใช้คนเดียว:

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

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

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

และนี่คือตัวอย่างของทรัพยากรย่อยที่เกี่ยวข้องกับผู้ใช้เฉพาะ:

GET /user/{id}/friends -> Returns a list of friends of given user

ทำความรู้จักกับเพื่อน (หลายต่อหลายลิงก์):

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

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

ใช้เอกพจน์และใช้ประโยชน์จากการประชุมภาษาอังกฤษเช่น "Business Directory"

หลายสิ่งหลายอย่างอ่านด้วยวิธีนี้: "Book Case", "Dog Pack", "Art Gallery", "Film Festival", "Car Lot" ฯลฯ

สิ่งนี้สะดวกตรงกับเส้นทาง URL จากซ้ายไปขวา ประเภทรายการทางด้านซ้าย ตั้งค่าประเภททางด้านขวา

ไม่GET /usersจริงๆเคยดึงข้อมูลการตั้งค่าของผู้ใช้หรือไม่? ไม่ปกติ มันดึงชุดของสตับที่มีรหัสและชื่อผู้ใช้ ดังนั้นมันไม่ได้จริงๆ/usersล่ะค่ะ มันเป็นดัชนีของผู้ใช้หรือ "ดัชนีผู้ใช้" ถ้าคุณต้องการ ทำไมไม่เรียกมันว่า? /user/indexมันเป็น เนื่องจากเราตั้งชื่อชุดประเภทเราสามารถมีหลายประเภทที่แสดงการคาดการณ์ที่แตกต่างกันของผู้ใช้โดยไม่ต้องใช้พารามิเตอร์การสืบค้นเช่นuser/phone-listหรือ/user/mailing-listหรือ

แล้ว User 300 ล่ะ? /user/300ก็ยังคง

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

ในการปิด HTTP สามารถตอบกลับคำขอเดียวได้เพียงครั้งเดียวเท่านั้น เส้นทางมักจะอ้างถึงบางสิ่งบางอย่างที่เป็นเอกเทศ

สำหรับฉันแล้วพหูพจน์จัดการคอลเลกชันในขณะที่เอกพจน์จัดการรายการภายในคอลเลกชันนั้น

คอลเล็กชันอนุญาตให้ใช้เมธอดGET / POST / DELETE

รายการอนุญาตวิธีการ GET / PUT / DELETE

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

โพสต์เมื่อ/ นักเรียนจะเพิ่มนักเรียนใหม่ในโรงเรียน

ลบเมื่อ/ นักเรียนจะลบนักเรียนทั้งหมดในโรงเรียน

ลบใน/ นักเรียน / 123จะลบนักเรียน 123 ออกจากโรงเรียน

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

หากต้องการขยายตัวอย่างเพิ่มเติมถ้า API ควรเปิดเผยโรงเรียนหลายแห่ง

ลบบน/ โรงเรียน / abc / นักศึกษาabcจะลบนักเรียนทุกคนในโรงเรียน

การเลือกคำที่เหมาะสมบางครั้งก็เป็นสิ่งที่ท้าทายด้วยตัวเอง เช่นcart_itemsหรือcart/itemsรู้สึกถูก ในทางตรงกันข้ามการลบcartให้ลบวัตถุรถเข็นที่เป็นของตัวเองออกและไม่ใช่รายการที่อยู่ในรถเข็น;)

เกี่ยวกับ:

/resource/(ไม่/resource)

/resource/ หมายความว่าเป็นโฟลเดอร์ที่มีสิ่งที่เรียกว่า "ทรัพยากร" มันเป็นโฟลเดอร์ "resouce"

และฉันก็คิดว่าหลักการตั้งชื่อของตารางฐานข้อมูลเหมือนกันตัวอย่างเช่นตารางที่เรียกว่า 'user' เป็น "ตารางผู้ใช้" มันมีสิ่งที่เรียกว่า "ผู้ใช้"

ฉันชอบที่จะใช้ทั้งพหูพจน์ ( /resources) และเอกพจน์ ( /resource/{id}) เพราะฉันคิดว่ามันแยกตรรกะระหว่างการทำงานกับการรวบรวมทรัพยากรและการทำงานบนทรัพยากรเดียวได้ชัดเจนยิ่งขึ้น

ในฐานะที่เป็นผลข้างเคียงที่สำคัญของสิ่งนี้มันยังสามารถช่วยป้องกันคนที่ใช้ API อย่างไม่ถูกต้อง ตัวอย่างเช่นพิจารณากรณีที่ผู้ใช้พยายามรับทรัพยากรโดยระบุ Id เป็นพารามิเตอร์ดังนี้:

GET /resources?Id=123

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

ในทางกลับกันเมื่อใช้รูปแบบเอกพจน์:

GET /resource?Id=123

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