REST APIs การกำหนดเวอร์ชัน แต่ละ API มีเวอร์ชันของตัวเอง

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

POST /api/v1/accounts
GET /api/v1/accounts/details

อย่างไรก็ตามฉันไม่เห็นการออกแบบที่เกี่ยวข้องกับแต่ละ API กล่าวอีกนัยหนึ่งเรารักษาเวอร์ชันของแต่ละ API แยกจากกัน เช่น:

POST /api/accounts/v2
GET /api/accounts/details/v3

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

อะไรคือข้อเสียของการใช้สไตล์นี้แทนสไตล์ทั่วไป?

สิ่งที่คุณเรียกเดียว APIs REST อาจจะเรียกว่า REST API ของชุดเฉพาะของทรัพยากรหรือทรัพยากร นอกจากนี้คุณยังสามารถมองไปที่มันเป็น REST API ของฟังก์ชัน เช่นซอฟต์แวร์ประเภทใดก็ตามแพคเกจทั้งหมดนั้นเป็นเวอร์ชั่น / อัปเดตไม่ใช่ฟังก์ชันการทำงานหรือทรัพยากรเดียว

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

จากนั้นเท่าที่ฉันเห็นข้อตกลงหลักของแผนการตั้งชื่อตัวระบุทรัพยากรที่เสนอของคุณคือ:

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

เมื่อสร้าง API หนึ่งในวัตถุประสงค์หลักของคุณคือทำให้ใช้งานง่าย ...

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

หากต้องการทราบข้อมูลเพิ่มเติมเกี่ยวกับแนวทางส่วนหัว HTTP โปรดดูคำตอบอื่น ๆ ด้านล่างและ: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

นี่เป็นวิธีที่ดียิ่งขึ้น: ใช้การเจรจาต่อรองเนื้อหาเพื่อกำหนดรุ่น API ของคุณด้วยContent-TypeและAcceptส่วนหัว:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

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

นอกจากนี้ยังช่วยให้คุณสามารถสนับสนุนรูปแบบใหม่ที่มีความแตกต่างกันความหมาย (ไม่เพียง แต่รุ่นที่แตกต่างกัน) บนอุปกรณ์ปลายทางเดียวกัน ตัวอย่างเช่นการโพสต์รายการบัญชี/api/accountsอาจหมายถึงการสร้างแบทช์และคุณไม่จำเป็นต้องสร้างจุดสิ้นสุด API แยกต่างหาก

สิ่งสำคัญคือถ้าคุณกำหนดจุดปลายแต่ละจุดแยกจากกันคุณจะต้องสามารถปรับใช้จุดปลายแต่ละจุดแยกกันได้

API มักจะมีหนึ่งเวอร์ชันเพราะจุดสิ้นสุดทั้งหมดอยู่ใน codebase เดียวกันดังนั้นจึงมีการขึ้นต่อกันที่ใช้ร่วมกันและมีการปรับใช้ร่วมกัน

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

นอกจากนี้คุณจะต้องมีทั้ง v1 และ v2 ของ API ของคุณในเวลาเดียวกัน โดยปกติจะทำโดยการปรับใช้แต่ละรุ่นไปยังเซิร์ฟเวอร์ที่แยกต่างหากและกำหนดเส้นทางการรับส่งข้อมูลตามลำดับ

หากคุณไม่มีรุ่น API เดียวสิ่งนี้จะซับซ้อนกว่านี้มาก