วิธีใดเป็นวิธีที่ดีที่สุดในการสร้าง URI REST ขณะนี้เรามีเวอร์ชัน # ใน URI เองเช่น
http://example.com/users/v4/1234/
สำหรับเวอร์ชัน 4 ของการเป็นตัวแทนนี้
เวอร์ชันอยู่ใน queryString หรือไม่ กล่าวคือ
http://example.com/users/1234?version=4
หรือการกำหนดเวอร์ชันทำได้ดีที่สุดด้วยวิธีอื่น?
คำตอบ:
ฉันจะบอกว่าทำให้เป็นส่วนหนึ่งของ URI เอง (ตัวเลือกที่ 1) ดีที่สุดเพราะ v4 ระบุทรัพยากรที่แตกต่างจาก v3 พารามิเตอร์แบบสอบถามเหมือนในตัวเลือกที่สองของคุณสามารถใช้ที่ดีที่สุดที่จะผ่านในเพิ่มเติม (แบบสอบถาม) ข้อมูลที่เกี่ยวข้องกับการร้องขอมากกว่าทรัพยากร
อย่าเวอร์ชัน URL เนื่องจาก ...
สมมติว่าทรัพยากรของคุณส่งคืนตัวแปร application / vnd.yourcompany.user + xml สิ่งที่คุณต้องทำคือสร้างการสนับสนุนสำหรับแอปพลิเคชันใหม่ / ประเภทสื่อ vnd.yourcompany.userV2 + xml และผ่านความมหัศจรรย์ของการเจรจาเนื้อหา v1 ของคุณและ ไคลเอนต์ v2 สามารถอยู่ร่วมกันได้อย่างสงบสุข
ในอินเทอร์เฟซ RESTful สิ่งที่ใกล้เคียงที่สุดที่คุณต้องทำสัญญาคือคำจำกัดความของประเภทสื่อที่แลกเปลี่ยนระหว่างไคลเอนต์และเซิร์ฟเวอร์
URL ที่ไคลเอ็นต์ใช้ในการโต้ตอบกับเซิร์ฟเวอร์ควรจัดเตรียมโดยเซิร์ฟเวอร์ที่ฝังอยู่ในการแสดงที่ดึงมาก่อนหน้านี้ URL เดียวที่ไคลเอ็นต์ต้องทราบคือ URL รากของอินเทอร์เฟซ การเพิ่มหมายเลขเวอร์ชันให้กับ URL จะมีค่าก็ต่อเมื่อคุณสร้าง URL บนไคลเอนต์ซึ่งคุณไม่ควรทำกับอินเทอร์เฟซ RESTful
หากคุณต้องการเปลี่ยนแปลงประเภทสื่อของคุณที่จะทำลายลูกค้าปัจจุบันของคุณให้สร้างใหม่และปล่อยให้ URL ของคุณอยู่คนเดียว!
และสำหรับผู้อ่านเหล่านั้นในปัจจุบันกล่าวว่าสิ่งนี้ไม่สมเหตุสมผลหากฉันใช้ application / xml และ application / json เป็นสื่อประเภท เราควรจะทำเวอร์ชันเหล่านั้นอย่างไร? คุณไม่. ประเภทสื่อเหล่านี้ค่อนข้างไร้ประโยชน์สำหรับอินเทอร์เฟซ RESTful เว้นแต่คุณจะแยกวิเคราะห์โดยใช้การดาวน์โหลดโค้ดซึ่งการกำหนดเวอร์ชันเป็นจุดที่สงสัย
อาฉันสวมหมวกใบเก่าที่ไม่พอใจอีกครั้ง
จากมุมมองของ ReST มันไม่สำคัญเลย ไม่ใช่ไส้กรอก.
ไคลเอนต์ได้รับ URI ที่ต้องการติดตามและถือว่าเป็นสตริงทึบแสง ใส่อะไรก็ได้ที่คุณต้องการลูกค้าไม่มีความรู้เกี่ยวกับสิ่งนั้นเป็นตัวระบุเวอร์ชัน
สิ่งที่ลูกค้ารู้คือสามารถประมวลผลประเภทสื่อได้และฉันจะแนะนำให้ทำตามคำแนะนำของ Darrel โดยส่วนตัวแล้วฉันรู้สึกว่าการต้องเปลี่ยนรูปแบบที่ใช้ในสถาปัตยกรรมที่เงียบสงบ 4 ครั้งควรนำมาซึ่งสัญญาณเตือนขนาดใหญ่ที่บ่งบอกว่าคุณกำลังทำอะไรผิดพลาดอย่างร้ายแรงและหลีกเลี่ยงความจำเป็นในการออกแบบประเภทสื่อของคุณเพื่อความยืดหยุ่นในการเปลี่ยนแปลง
แต่ไม่ว่าจะด้วยวิธีใดไคลเอ็นต์สามารถประมวลผลเอกสารที่มีรูปแบบที่เข้าใจได้และติดตามลิงก์ในเอกสาร ควรรู้เกี่ยวกับความสัมพันธ์ของลิงก์ (ช่วงการเปลี่ยนภาพ) ดังนั้นสิ่งที่อยู่ใน URI จึงไม่เกี่ยวข้องโดยสิ้นเชิง
ฉันเองจะโหวตให้http: // localhost / 3f3405d5-5984-4683-bf26-aca186d21c04
ตัวระบุที่ถูกต้องสมบูรณ์ซึ่งจะป้องกันไม่ให้นักพัฒนาไคลเอ็นต์รายอื่นหรือบุคคลที่สัมผัสระบบตั้งคำถามว่าควรใส่ v4 ไว้ที่จุดเริ่มต้นหรือตอนท้ายของ URI (และฉันขอแนะนำว่าจากมุมมองของเซิร์ฟเวอร์คุณไม่ควรมี 4 เวอร์ชัน แต่สื่อ 4 ประเภท)
คุณไม่ควรใส่เวอร์ชันใน URL คุณควรใส่เวอร์ชันในส่วนหัวยอมรับของคำขอ - ดูโพสต์ของฉันในหัวข้อนี้:
แนวทางปฏิบัติที่ดีที่สุดสำหรับการกำหนดเวอร์ชัน API?
หากคุณเริ่มติดเวอร์ชันใน URL คุณจะพบ URL โง่ ๆ เช่นนี้: http://company.com/api/v3.0/customer/123/v2.0/orders/4321/
และยังมีปัญหาอื่น ๆ อีกมากมายที่กำลังคืบคลานเข้ามาเช่นกัน - ดูบล็อกของฉัน: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html
คำถาม SO (เฉพาะน้อยกว่า) เหล่านี้เกี่ยวกับการกำหนดเวอร์ชัน REST API อาจเป็นประโยชน์:
มี 4 วิธีที่แตกต่างกันในการกำหนดเวอร์ชัน API:
การเพิ่มเวอร์ชันในเส้นทาง URI:
http://example.com/api/v1/foo
http://example.com/api/v2/foo
เมื่อคุณทำลายการเปลี่ยนแปลงคุณต้องเพิ่มเวอร์ชันเช่น: v1, v2, v3 ...
คุณสามารถติดตั้งคอนโทรลเลอร์ในโค้ดของคุณได้ดังนี้:
@RestController
public class FooVersioningController {
@GetMapping("v1/foo")
public FooV1 fooV1() {
return new FooV1("firstname lastname");
}
@GetMapping("v2/foo")
public FooV2 fooV2() {
return new FooV2(new Name("firstname", "lastname"));
}
ขอการกำหนดเวอร์ชันพารามิเตอร์:
http://example.com/api/v2/foo/param?version=1
http://example.com/api/v2/foo/param?version=2
พารามิเตอร์เวอร์ชันอาจเป็นทางเลือกหรือจำเป็นขึ้นอยู่กับว่าคุณต้องการใช้ API อย่างไร
การใช้งานอาจคล้ายกับสิ่งนี้:
@GetMapping(value = "/foo/param", params = "version=1")
public FooV1 paramV1() {
return new FooV1("firstname lastname");
}
@GetMapping(value = "/foo/param", params = "version=2")
public FooV2 paramV2() {
return new FooV2(new Name("firstname", "lastname"));
}
การส่งผ่านส่วนหัวที่กำหนดเอง:
http://localhost:8080/foo/produces
ด้วยส่วนหัว:
headers[Accept=application/vnd.company.app-v1+json]
หรือ:
headers[Accept=application/vnd.company.app-v2+json]
ข้อได้เปรียบที่ใหญ่ที่สุดของรูปแบบนี้ส่วนใหญ่เป็นความหมาย: คุณไม่ได้ทำให้ URI ยุ่งเหยิงกับสิ่งที่เกี่ยวข้องกับการกำหนดเวอร์ชัน
การใช้งานที่เป็นไปได้:
@GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v1+json")
public FooV1 producesV1() {
return new FooV1("firstname lastname");
}
@GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v2+json")
public FooV2 producesV2() {
return new FooV2(new Name("firstname", "lastname"));
}
การเปลี่ยนชื่อโฮสต์หรือใช้เกตเวย์ API:
โดยพื้นฐานแล้วคุณกำลังย้าย API จากชื่อโฮสต์หนึ่งไปยังอีกชื่อหนึ่ง คุณอาจเรียกสิ่งนี้ว่าการสร้าง API ใหม่กับทรัพยากรเดียวกัน
นอกจากนี้คุณสามารถทำได้โดยใช้ API เกตเวย์
หากบริการ REST ต้องการการพิสูจน์ตัวตนก่อนใช้งานคุณสามารถเชื่อมโยงคีย์ / โทเค็น API กับเวอร์ชัน API และกำหนดเส้นทางภายในได้อย่างง่ายดาย หากต้องการใช้ API เวอร์ชันใหม่อาจต้องใช้คีย์ API ใหม่โดยลิงก์กับเวอร์ชันนั้น
ขออภัยโซลูชันนี้ใช้ได้กับ API ที่ใช้การตรวจสอบสิทธิ์เท่านั้น อย่างไรก็ตามจะไม่เก็บเวอร์ชันต่างๆจาก URI
ฉันต้องการสร้าง API ที่กำหนดเวอร์ชันและพบว่าบทความนี้มีประโยชน์มาก:
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
มีส่วนเล็ก ๆ ใน "ฉันต้องการให้ API ของฉันเป็นเวอร์ชัน" ฉันพบว่ามันเรียบง่ายและเข้าใจง่าย ประเด็นสำคัญคือการใช้ช่องยอมรับในส่วนหัวเพื่อส่งผ่านข้อมูลเวอร์ชัน
ฉันจะรวมเวอร์ชันเป็นค่าทางเลือกที่ส่วนท้ายของ URI ซึ่งอาจเป็นคำต่อท้ายเช่น / V4 หรือพารามิเตอร์การค้นหาตามที่คุณอธิบายไว้ คุณอาจเปลี่ยนเส้นทาง / V4 ไปยังพารามิเตอร์เคียวรีเพื่อให้คุณรองรับทั้งสองรูปแบบ
หากคุณใช้ URI ในการกำหนดเวอร์ชันหมายเลขเวอร์ชันควรอยู่ใน URI ของรูท API ดังนั้นตัวระบุทรัพยากรทุกตัวสามารถรวมไว้ได้
ในทางเทคนิค REST API ไม่ทำลายโดยการเปลี่ยนแปลง URL (ผลลัพธ์ของข้อ จำกัด ของอินเตอร์เฟสที่เหมือนกัน) จะแตกก็ต่อเมื่อความหมายที่เกี่ยวข้อง (เช่นคำศัพท์ RDF เฉพาะของ API) เปลี่ยนไปในลักษณะที่เข้ากันไม่ได้ย้อนหลัง (หายาก) ปัจจุบัน ppl จำนวนมากไม่ใช้ลิงก์สำหรับการนำทาง (ข้อ จำกัด ของ HATEOAS) และคำศัพท์เพื่อใส่คำอธิบายประกอบการตอบกลับ REST (ข้อ จำกัด ของข้อความอธิบายตัวเอง) นั่นคือสาเหตุที่ลูกค้าของพวกเขาหยุดทำงาน
ประเภท MIME ที่กำหนดเองและการกำหนดเวอร์ชันประเภท MIME ไม่สามารถช่วยได้เนื่องจากการใส่ข้อมูลเมตาที่เกี่ยวข้องและโครงสร้างของการแสดงลงในสตริงสั้น ๆ ไม่ได้ผล Ofc ข้อมูลเมตาและโครงสร้างมักจะเปลี่ยนแปลงดังนั้นหมายเลขเวอร์ชันก็เช่นกัน ...
เพื่อที่จะตอบคำถามของคุณวิธีที่ดีที่สุดในการใส่คำอธิบายประกอบการร้องขอและการตอบสนองของคุณด้วย vocabs ( Hydra , เชื่อมโยงข้อมูล ) และลืมเวอร์ชันหรือใช้โดยเฉพาะการเปลี่ยนแปลงคำศัพท์ที่เข้ากันได้ย้อนหลังไม่ใช่ (ตัวอย่างเช่นถ้าคุณต้องการที่จะเปลี่ยนคำศัพท์กับอีกหนึ่ง)
ฉันโหวตให้ทำสิ่งนี้ในประเภท mime แต่ไม่ใช่ใน URL แต่เหตุผลไม่เหมือนกับผู้ชายคนอื่น ๆ
ฉันคิดว่า URL ควรไม่ซ้ำกัน (ยกเว้นการเปลี่ยนเส้นทางเหล่านั้น) สำหรับการค้นหาทรัพยากรที่ไม่ซ้ำกัน ดังนั้นถ้าคุณยอมรับ/v2.0ใน URL ที่ว่าทำไมมันไม่ได้/ver2.0หรือ/v2/หรือ/v2.0.0? หรือแม้แต่-alphaและ-beta? (จากนั้นมันก็กลายเป็นแนวคิดของsemver โดยสิ้นเชิง )
ดังนั้นเวอร์ชันในประเภท mime จึงเป็นที่ยอมรับได้มากกว่า URL