HTTP API ควรส่งคืนเนื้อหาเสมอหรือไม่

มีมาตรฐานบางอย่างเกี่ยวกับการตอบกลับ HTTP API หรือไม่

หลังจากอ่านหัวข้อสนทนานี้ฉันเริ่มสงสัย เรากำลังพัฒนา HTTP JSON API สาธารณะของเราในที่ทำงานของฉันและเราจะไม่ส่งคืนสิ่งใดเมื่อไม่จำเป็นอย่างเคร่งครัด (เช่น PUT to / resource / {id} เท่านั้นส่งคืน 200 เมื่อตกลงหรือรหัส 4XX หรือ 5XX ที่เกี่ยวข้อง แต่ไม่ ร่างกาย JSON)

เราควรคืนค่าตัวแบบทั่วไป{"success":true}เช่นที่พวกเขาพูดคุยเกี่ยวกับลิงก์ข้างต้นหรือไม่มันก็โอเคที่จะคืนค่าส่วน "โมฆะ" และจัดการทุกอย่างด้วยรหัสตอบกลับ http?

เกี่ยวกับ PUT แต่ใช้กับ POST เช่นกัน จำเพาะ HTTPมาตรา 9 เป็นที่ว่างเปล่าเล็ก ๆ น้อย ๆ เกี่ยวกับกฎหรือแม้กระทั่งคำแนะนำ (ควร) เมื่อมันมาถึงสถานการณ์ที่คุณจะอธิบาย บรรทัดที่เกี่ยวข้องกับคำถามของคุณครอบคลุมมากที่สุดโดย:

หากมีการสร้างทรัพยากรใหม่เซิร์ฟเวอร์ต้นทางต้องแจ้งตัวแทนผู้ใช้ผ่านการตอบกลับ 201 (สร้าง) หากมีการแก้ไขทรัพยากรที่มีอยู่ให้ส่งรหัสตอบกลับ 200 (OK) หรือ 204 (ไม่มีเนื้อหา) เพื่อบ่งชี้ว่าการร้องขอสำเร็จ

ฉันไม่คิดว่าฉันจะนอนไม่หลับ แต่ฉันจะถามคุณจะได้อะไรจากการเพิ่ม JSON เข้าไปในคำตอบ? คุณเพิ่งจัดกลุ่ม (ตกลงจัดกลุ่มอาจมากเกินไป!) การตอบสนองจะทำซ้ำได้อย่างแม่นยำน้อยกว่าสิ่งที่รหัสสถานะควรบอกคุณแล้ว หาก PUT ของคุณส่งผลให้วัตถุใหม่คืนค่า 201 (ตามความตั้งใจของ PUT) หากมีการอัพเดทวัตถุคืน 204

อนึ่ง API กันแทนที่จะเป็น 200 ถ้าคุณไม่คืนสิ่งใดให้ใช้ 204

สมมติว่าคุณกำลังพัฒนาชุดอินเตอร์เฟส RESTful ไม่มีมาตรฐานต่อหนึ่งดังนั้นสิ่งที่คุณทำเอกสารดี ,, ให้ตัวอย่างและทุกอย่างจะไม่เป็นไร

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

มีมาตรฐาน JSON APIแบบเปิดที่ระบุ:

• วัตถุ JSON จะต้องอยู่ที่รูทของเอกสารตอบกลับ JSON API ทุกรายการ (ตัวเอียงเป็นตัวแทนของสิ่งที่ฉันเพิ่มเพื่อชี้แจงข้อความ)

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

แอปพลิเคชั่นบางตัว (เช่นElasticSearch ) ให้ JSON API แบบเต็มและมีเมตาดาต้าอยู่เสมอเพื่อให้คุณมีความคิดที่ดีขึ้นเกี่ยวกับวิธีที่เซิร์ฟเวอร์กำลังจัดการข้อมูลของคุณ วัตถุตอบกลับมาตรฐานจะบอกคุณเกี่ยวกับสุขภาพของดัชนีหากคำขอเกิดข้อผิดพลาดมีกี่โหนดที่ได้รับผลกระทบ ฯลฯ ElasticSearch ใช้ "application / json" สำหรับประเภท mime ดังนั้นจึงไม่น่าที่พวกเขาจะใช้แนวทางใน มาตรฐาน jsonapi.org

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

ไม่มีตัวอย่างสำหรับ 204 คำตอบที่เราจะต้องไม่รวมเนื้อหาของข้อความ {สำเร็จ | สถานะ | isSuccessful: true} ซ้ำซ้อน

ในทางปฏิบัติ (หรือฉันควรจะพูดใน jquery รุ่นต่อมา) การตอบสนองที่ว่างเปล่าสำหรับประเภทเนื้อหาของแอปพลิเคชัน / json ทำให้เกิดข้อผิดพลาด ฉันเข้าใจการโต้แย้งว่าเป็นเพราะแอปพลิเคชัน / json จะต้องมีเนื้อหาของ json ที่ถูกต้อง ดังนั้นการตอบสนองที่ว่างเปล่าสำหรับประเภทเนื้อหา application / json จะเป็น 'null' หรือ '{}' ซึ่งเป็น json ที่ถูกต้อง

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

หมายเหตุฉันจำได้เพียง 204 ครั้งเท่านั้นสำหรับการห้ามส่งคืนข้อความอย่างชัดเจน สิ่งที่เราพบคือเราไม่สามารถใช้ 204 ได้เสมอปัญหาคือส่วนหัวการตอบสนองแบบหล่นของ MSIE สำหรับ 204 คำตอบดังนั้นจึงไม่มีเนื้อหาและส่วนหัวซึ่งไม่ดี เนื่องจากหลายคนใช้ MSIE เราจึงต้องเปลี่ยนเป็น 200 สถานะ

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

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

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

สำหรับการร้องขอ POST ที่เป็นตัวแทนของการดำเนินการแทนเพียงแค่การสร้างทรัพยากร (ไม่ได้เป็นอย่างสงบ แต่ยังคงมีประโยชน์ในทางปฏิบัติ) ซึ่งไม่ได้มีข้อมูลที่เป็นประโยชน์ที่จะกลับมาผมจะตอบกลับที่ประกอบด้วยวัตถุ JSON {}ที่ว่างเปล่าเช่น ด้วยวิธีนี้ลูกค้าจะได้รับการตอบสนองที่ถูกต้องและการเพิ่มข้อมูลบางอย่างในภายหลังไม่น่าจะทำลายได้

สำหรับคำร้องขอ DELETE ที่ส่งคืน 204 และเนื้อความว่างเปล่าเป็นเรื่องธรรมดาซึ่งเหมาะสมเนื่องจากทรัพยากรไม่มีอยู่หลังจากนั้น

ฉันขอแนะนำให้คืนเฉพาะสิ่งที่ต้องการ + ความกระจ่างเล็กน้อย

ตัวอย่างเช่นขึ้นอยู่กับวิธีใช้ API ของคุณคุณสามารถรวมสำเนาของวัตถุตามที่มีอยู่หลังจากบันทึก

ดังนั้น POST ของ {key: 123} อาจส่งคืน {key: 123, foo: 'bar'}

แนวคิดพื้นฐานคือจะเป็นการดีกว่าถ้าส่งคืนออบเจกต์แล้วต้องค้นหาอีกครั้ง

ดังกล่าวจากผู้ใช้ API ของคุณไม่ต้องการวัตถุไม่จำเป็นต้องส่งคืนวัตถุ

ฉันมักจะส่งกลับ {สำเร็จ: จริง} หรือบางอย่างเมื่อไม่มีวัตถุที่ต้องใช้ใน POST PUT และ PATCH เพราะมันทำให้การรับปลายทางง่ายขึ้น ที่กล่าวว่าดีกว่า 99% ของเวลาในการคืนค่าการแสดงวัตถุที่บันทึกไว้มันหายากที่พวกเขาไม่ต้องการมันและ "ถูก" เพื่อส่งทั้งหมดในคำขอเดียวจากนั้นในสอง

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

การส่งคืน 200 {สำเร็จ: จริง} ทำให้ผู้คนสามารถเขียนโค้ดได้ทั้งสองทาง:

if response.code == 200
  do stuff
end

และ

if response.body.success
  do stuff
end

นอกจากนี้ยังไม่ยากที่จะทำในด้านของคุณ

สุดท้าย (ขออภัยสำหรับโครงสร้างคำตอบของ poos) โดยการให้ JSON สาธารณะของคุณเลิกควบคุมอย่างมากเกี่ยวกับวิธีการใช้งาน ลูกค้าบางคนอาจตอบสนองต่อร่างกายที่แตกต่างกัน (หรือไม่มี) หรือรหัสสถานะ