รหัสสถานะ HTTP ที่ถูกต้องสำหรับ:“ API รุ่นนี้ถูกยกเลิกแล้ว” คืออะไร?

ฉันมี RESTful API มี 3 เวอร์ชันคือ v1, v2 และ v3 ฉันกำลังจะเผยแพร่ v4 และเราได้ตัดสินใจหยุด v1 ซึ่งหมายความว่าคำขอทั้งหมดhttp://example.com/v1/resourceจะล้มเหลว แต่การโทรไปhttp://example.com/v2/resourceยังจะยังคงทำงานต่อไป

วิธีที่เหมาะสมในการบ่งชี้ความล้มเหลวคืออะไร? ฉันถือว่าใช้410 GONEรหัสสถานะ แต่นั่นแสดงว่าทรัพยากรไม่สามารถใช้ได้อีกต่อไป ทรัพยากรที่เป็นไปได้ยังคงมีอยู่ แต่จะต้องมีการร้องขอในวิธีที่แตกต่าง

ฉันยังพิจารณา400รหัสสถานะทั่วไปด้วย แต่มันก็ดูแปลก ๆ เช่นกัน มีคำตอบมาตรฐานสำหรับสิ่งนี้หรือไม่?

ดูเหมือนจะไม่ได้มาตรฐาน

StackOverflow ตอบสนองต่อ 410 GONE แต่ฉันคิดว่า 301 MOVED อย่างต่อเนื่องเหมาะสมกว่า

เพื่อให้ทางเลือกที่ถูกต้องเราต้องดูกรณีเฉพาะของคุณ หากเป้าหมายของคุณคือการโทรทั้งหมดไปยัง API v1 ล้มเหลวโดยไม่ต้องดำเนินการใด ๆ อีก 410 GONE สามารถใช้งานได้ หากคุณต้องการความต่อเนื่องเช่นการเปลี่ยนเส้นทางไคลเอ็นต์ไปยัง API รุ่นใหม่ที่ซึ่งการโทรของพวกเขาอาจประสบความสำเร็จ 3XX ใช้งานได้ แต่คุณเลือกแบบไหน? ฉันคิดว่าถ้าคุณกำลังพยายามปิด API v1, 301 MOVED จะช่วยระบุว่าดีกว่า 303 SEE OTHER เพราะ 301 แนะนำว่าคำขอในอนาคตทั้งหมดควรทำกับ URL ใหม่ในขณะที่ 303 ไม่ได้ระบุว่าสถานการณ์นี้เป็นหรือไม่ ถาวร.

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

รหัสสถานะ HTTP

รหัสสถานะ HTTP 302 นั้นกว้างเกินไป แต่เดิมและมีการนำไปใช้ / ใช้อย่างไม่ถูกต้องดังนั้น 303 และ 307 จึงถูกสร้างขึ้นเพื่อแยกความแตกต่างระหว่างกรณีใช้งานคู่ของ 302 API บางตัวใช้ 303 เพื่อจุดประสงค์อื่น

301 ย้ายอย่างต่อเนื่อง - รหัสสถานะ 301 (ย้ายอย่างถาวร) บ่งชี้ว่าทรัพยากรเป้าหมายได้รับการกำหนด URI ถาวรใหม่และการอ้างอิงในอนาคตใด ๆ กับทรัพยากรนี้ควรใช้หนึ่งใน URI ที่แนบมา

302 FOUND - รหัสสถานะ 302 (พบ) ระบุว่าทรัพยากรเป้าหมายอยู่ภายใต้ URI อื่นชั่วคราว เนื่องจากการเปลี่ยนเส้นทางอาจมีการเปลี่ยนแปลงในบางโอกาสลูกค้าควรใช้ URI คำขอที่มีประสิทธิภาพต่อไปสำหรับคำขอในอนาคต

303 SEE OTHER - การตอบสนอง 303 ต่อคำขอ GET บ่งชี้ว่าเซิร์ฟเวอร์ต้นทางไม่มีการแสดงทรัพยากรเป้าหมายที่สามารถถ่ายโอนโดยเซิร์ฟเวอร์ผ่าน HTTP อย่างไรก็ตามค่าฟิลด์ Location หมายถึงทรัพยากรที่เป็นคำอธิบายของทรัพยากรเป้าหมายเช่นการร้องขอการดึงข้อมูลบนทรัพยากรอื่นนั้นอาจส่งผลให้เกิดการแสดงที่เป็นประโยชน์ต่อผู้รับโดยไม่ได้หมายความว่ามันหมายถึงทรัพยากรเป้าหมายดั้งเดิม

410 GONE - รหัสสถานะ 410 (หายไป) บ่งชี้ว่าการเข้าถึงทรัพยากรเป้าหมายไม่สามารถใช้งานได้ที่เซิร์ฟเวอร์ต้นทางอีกต่อไปและเงื่อนไขนี้น่าจะเป็นแบบถาวร หากเซิร์ฟเวอร์ต้นทางไม่รู้หรือไม่มีสิ่งอำนวยความสะดวกในการตรวจสอบว่าเงื่อนไขนั้นถาวรหรือไม่ควรใช้รหัสสถานะ 404 (ไม่พบ) แทน

API ที่มีอยู่จะจัดการสิ่งนี้ได้อย่างไร

บางทีคุณสามารถรับหน้าจากYoutube APIของ Google :

เมื่อคำขอ API ล้มเหลว YouTube จะส่งคืนรหัสตอบกลับ HTTP 4xx หรือ 5xx ที่ระบุความล้มเหลวโดยทั่วไปรวมถึงการตอบกลับ XML ที่ให้ข้อมูลเฉพาะเพิ่มเติมเกี่ยวกับข้อผิดพลาดที่ทำให้เกิดความล้มเหลว สำหรับข้อผิดพลาดแต่ละครั้งการตอบสนอง XML รวมองค์ประกอบโดเมนองค์ประกอบรหัสและองค์ประกอบตำแหน่ง

• BigCommerce APIใช้ 302 FOUND
• หลักเกณฑ์ REST API ของ Atlassianแนะนำไว้ที่ 301 ย้ายเป็นประจำพร้อมกับรหัสย่อยที่อธิบายข้อผิดพลาดโดยละเอียด วิธีนี้คล้ายกับแนวทางของ Youtube API

อ่านเพิ่มเติม:

• REST API มีวิธีการอย่างไร
• การออกแบบ Netflix API: เมื่อใดที่เจ้าชู้เทรนด์

การเปลี่ยนเส้นทางเหมาะสำหรับทรัพยากรที่มีการย้าย แทนที่จะเปลี่ยนเส้นทาง 301 แบบถาวร (ซึ่งจะระบุการเปลี่ยนชื่อโดยไม่มีการเปลี่ยนแปลง API) ฉันจะใช้การเปลี่ยนเส้นทาง 303 "See Other"

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

10.5.2 ไม่ดำเนินการ 501

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

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

ฉันจะใช้ 503 กับข้อความว่าบริการไม่พร้อมใช้งานและระบุว่าจะใช้เวอร์ชันที่ใหม่กว่า ข้อความนี้สามารถส่งคืนได้ 50% ของการโทรและเวลาจะค่อยๆเพิ่มขึ้นเป็น 100%

สำหรับการย้ายข้อมูลแบบโปร่งใสฉันจะใช้308 - การเปลี่ยนเส้นทางถาวรเนื่องจากวิธีนี้ไม่ได้แก้ไขคำกริยา (POST จะเป็น POST) ซึ่งต่างจาก 301