ข้อผิดพลาด REST API คืนแนวทางปฏิบัติที่ดี [ปิด]

ฉันกำลังมองหาคำแนะนำเกี่ยวกับแนวทางปฏิบัติที่ดีเมื่อต้องส่งคืนข้อผิดพลาดจาก REST API ฉันกำลังทำงานกับ API ใหม่เพื่อให้ฉันสามารถทิศทางใดก็ได้ในขณะนี้ ประเภทเนื้อหาของฉันคือ XML ในขณะนี้ แต่ฉันวางแผนที่จะสนับสนุน JSON ในอนาคต

ตอนนี้ฉันกำลังเพิ่มข้อผิดพลาดบางอย่างเช่นลูกค้าพยายามเพิ่มทรัพยากรใหม่ แต่มีโควต้าการจัดเก็บข้อมูลเกิน ฉันกำลังจัดการกรณีข้อผิดพลาดบางอย่างด้วยรหัสสถานะ HTTP (401 สำหรับการตรวจสอบสิทธิ์, 403 สำหรับการให้สิทธิ์และ 404 สำหรับคำขอที่ไม่ดีธรรมดา) ฉันตรวจดูรหัสข้อผิดพลาด HTTP ที่มีความสุข แต่ไม่มีช่วง 400-417 ที่ดูเหมือนจะถูกรายงานข้อผิดพลาดเฉพาะแอปพลิเคชัน ดังนั้นในตอนแรกฉันถูกล่อลวงให้ส่งคืนข้อผิดพลาดแอปพลิเคชันของฉันด้วย 200 OK และ XML ที่ระบุเฉพาะ (เช่นจ่ายเงินให้เรามากขึ้นและคุณจะได้รับพื้นที่เก็บข้อมูลที่คุณต้องการ!) แต่ฉันหยุดคิดเกี่ยวกับมัน ยักด้วยความกลัว) นอกจากนี้ฉันรู้สึกว่าฉันแบ่งการตอบสนองข้อผิดพลาดออกเป็นกรณีที่แตกต่างกันเนื่องจากบางรายการเป็นรหัสสถานะ HTTP ที่ขับเคลื่อนด้วยและอื่น ๆ เป็นเนื้อหาที่ขับเคลื่อน

ดังนั้นคำแนะนำอุตสาหกรรมคืออะไร? แนวทางปฏิบัติที่ดี (โปรดอธิบายว่าทำไม!) และจากลูกค้า POV การจัดการข้อผิดพลาดประเภทใดใน REST API ทำให้ชีวิตของรหัสลูกค้าง่ายขึ้น?

ดังนั้นในตอนแรกฉันถูกล่อลวงให้ส่งคืนข้อผิดพลาดแอปพลิเคชันของฉันด้วย 200 OK และ XML ที่ระบุเฉพาะ (เช่นจ่ายเงินให้เรามากขึ้นและคุณจะได้รับพื้นที่เก็บข้อมูลที่คุณต้องการ!) แต่ฉันหยุดคิดเกี่ยวกับมัน ยักด้วยความกลัว)

ฉันจะไม่คืน 200 ถ้าไม่มีอะไรผิดปกติกับคำขอ จากRFC2616 , 200 หมายถึง "คำขอประสบความสำเร็จ"

หากเกินโควต้าการจัดเก็บของลูกค้า (ด้วยเหตุผลใดก็ตาม) ฉันจะส่งคืน 403 (ต้องห้าม):

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

สิ่งนี้บอกลูกค้าว่าคำขอนั้นตกลง แต่ล้มเหลว (บางอย่างที่ 200 ไม่ทำ) สิ่งนี้ยังให้โอกาสคุณในการอธิบายปัญหา (และวิธีแก้ปัญหา) ในส่วนการตอบกลับ

คุณมีเงื่อนไขข้อผิดพลาดอื่นใดอีกบ้าง

แหล่งข้อมูลที่ดีในการเลือกรหัสข้อผิดพลาด HTTP ที่ถูกต้องสำหรับ API ของคุณ: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

ข้อความที่ตัดตอนมาจากบทความ:

เริ่มต้นที่ไหน:

2XX / 3xx:

4XX:

5XX:

ตัวเลือกหลักคือคุณต้องการใช้รหัสสถานะ HTTP เป็นส่วนหนึ่งของ REST API หรือไม่

ทั้งสองวิธีทำงานได้ดี ฉันยอมรับว่าหนึ่งในแนวคิดของ REST อย่างเคร่งครัดคือคุณควรใช้รหัสสถานะ HTTP เป็นส่วนหนึ่งของ API ของคุณ (คืน 200 หรือ 201 สำหรับการดำเนินการที่ประสบความสำเร็จและ 4xx หรือ 5xx ขึ้นอยู่กับกรณีข้อผิดพลาดต่างๆ) อย่างไรก็ตาม ไม่มีตำรวจ REST คุณสามารถทำสิ่งที่คุณต้องการ. ฉันได้เห็น API ที่ไม่ใช่ REST ที่ยิ่งใหญ่กว่าที่เรียกว่า "RESTful"

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

รหัสสถานะ HTTP เป็นส่วนหนึ่งของ API ของคุณ

1. คุณจะต้องเลือกรหัส 4xx ที่เหมาะสมกับเงื่อนไขข้อผิดพลาดของคุณ คุณสามารถรวมข้อความที่เหลือ xml หรือข้อความธรรมดาเป็นเพย์โหลดที่มีรหัสย่อยและความคิดเห็นเชิงอธิบาย

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

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

รหัสสถานะ HTTP ไม่ได้เป็นส่วนหนึ่งของ API ของคุณ

1. รหัสสถานะ HTTP จะเป็น 200 หากแอปของคุณได้รับคำขอจากนั้นตอบกลับ (ทั้งกรณีความสำเร็จและข้อผิดพลาด)

2. คำตอบทั้งหมดของคุณควรมีข้อมูล "ซองจดหมาย" หรือ "ส่วนหัว" โดยทั่วไปแล้วสิ่งที่ชอบ:

   envelope_ver: 1.0
   สถานะ: # ใช้รหัสใด ๆ ที่คุณชอบ จองรหัสเพื่อความสำเร็จ
   msg: "ok" # สตริงมนุษย์ที่แสดงรหัส มีประโยชน์สำหรับการดีบัก
   data: ... # ข้อมูลการตอบกลับหากมี

3. วิธีการนี้สามารถทำได้ง่ายขึ้นสำหรับลูกค้าเนื่องจากสถานะสำหรับการตอบสนองอยู่ในสถานที่เดียวกันเสมอ (ไม่จำเป็นต้องใช้รหัสย่อย) ไม่ จำกัด รหัสไม่จำเป็นต้องดึงสถานะ HTTP ระดับรหัส

นี่คือโพสต์ที่มีแนวคิดคล้ายกัน: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

ประเด็นหลัก:

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

2. เอกสาร...

โปรดจำไว้ว่ามีรหัสสถานะมากขึ้นกว่าที่กำหนดไว้ใน HTTP / 1.1 RFCs รีจิสทรี IANA ที่http://www.iana.org/assignments/http-status-codes สำหรับกรณีที่คุณกล่าวถึงรหัสสถานะ 507 เสียงถูกต้อง

อย่างที่คนอื่น ๆ ชี้ไปการมีเอนทิตีการตอบสนองในรหัสข้อผิดพลาดนั้นสามารถทำได้อย่างสมบูรณ์

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

มีข้อผิดพลาดสองประเภท ข้อผิดพลาดของแอปพลิเคชันและข้อผิดพลาด HTTP ข้อผิดพลาด HTTP เป็นเพียงเพื่อให้ตัวจัดการ AJAX ของคุณรู้ว่าสิ่งต่าง ๆ ดีและไม่ควรใช้เพื่อสิ่งอื่น

5xx เซิร์ฟเวอร์ผิดพลาด

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

สำเร็จ 2xx

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

อย่างไรก็ตามวิธีที่คุณออกแบบข้อผิดพลาดของแอปพลิเคชันนั้นขึ้นอยู่กับคุณจริงๆ กองมากเกินเช่นส่งออกวัตถุที่มีresponse, dataและmessageคุณสมบัติ การตอบกลับที่ฉันเชื่อว่ามีtrueหรือfalseเพื่อระบุว่าการดำเนินการนั้นสำเร็จหรือไม่ ข้อมูลมีส่วนของข้อมูล (โดยปกติสำหรับการอ่าน) และข้อความมีข้อมูลเมตาเพิ่มเติมหรือข้อความที่มีประโยชน์ (เช่นข้อความแสดงข้อผิดพลาดเมื่อresponseมีfalse)

ฉันรู้ว่านี่มันช้าไปมากสำหรับงานปาร์ตี้ แต่ตอนนี้ในปี 2013 เรามีสื่อบางประเภทที่จะครอบคลุมการจัดการข้อผิดพลาดในแฟชั่นแบบกระจาย (RESTful) ทั่วไป ดู "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) และ "รายละเอียดปัญหาสำหรับ HTTP APIs", application / problem + json ( https: // tools ietf.org/html/draft-nottingham-http-problem-05 )

ตกลง ปรัชญาพื้นฐานของ REST คือการใช้โครงสร้างพื้นฐานของเว็บ รหัสสถานะ HTTP เป็นเฟรมเวิร์กการส่งข้อความที่อนุญาตให้ฝ่ายต่างๆสื่อสารกันโดยไม่ต้องเพิ่มเพย์โหลด HTTP พวกเขาได้รับการจัดตั้งขึ้นแล้วรหัสสากลแสดงสถานะของการตอบสนองดังนั้นจึงเป็นที่สงบเงียบอย่างแท้จริงแอปพลิเคชันจะต้องใช้กรอบการทำงานนี้เพื่อสื่อสารสถานะการตอบสนอง

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

การสร้างแบบจำลอง API ของคุณใน 'การปฏิบัติที่ดีที่สุด' ที่มีอยู่อาจเป็นวิธีที่จะไป ตัวอย่างเช่นนี่คือวิธีที่ Twitter จัดการกับรหัสข้อผิดพลาด https://developer.twitter.com/en/docs/basics/response-codes

โปรดยึดความหมายของโปรโตคอล ใช้ 2xx สำหรับการตอบกลับที่ประสบความสำเร็จและ 4xx, 5xx สำหรับการตอบกลับข้อผิดพลาดไม่ว่าจะเป็นข้อยกเว้นทางธุรกิจของคุณหรืออื่น ๆ หากใช้ 2xx สำหรับการตอบสนองใด ๆ เป็นกรณีการใช้งานที่ตั้งใจไว้ในโปรโตคอลพวกเขาจะไม่มีรหัสสถานะอื่นในตอนแรก

อย่าลืมข้อผิดพลาด 5xx เช่นกันสำหรับข้อผิดพลาดของแอปพลิเคชัน

ในกรณีนี้ประมาณ 409 (ความขัดแย้ง) คืออะไร? นี่ถือว่าผู้ใช้สามารถแก้ไขปัญหาได้โดยการลบทรัพยากรที่เก็บไว้

มิฉะนั้น 507 (ไม่ใช่มาตรฐานทั้งหมด) อาจใช้งานได้เช่นกัน ฉันจะไม่ใช้ 200 ยกเว้นว่าคุณใช้ 200 เพื่อหาข้อผิดพลาดโดยทั่วไป

หากเกินโควต้าของลูกค้านั่นเป็นข้อผิดพลาดของเซิร์ฟเวอร์ให้หลีกเลี่ยง 5xx ในอินสแตนซ์นี้