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

คำขอที่ประสบความสำเร็จ:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

คำขอล้มเหลว:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

ใช่มีสองมาตรฐาน (แม้ว่าจะมีเสรีภาพในความหมายของมาตรฐาน) ที่เกิดขึ้น:

1. JSON API - JSON API ครอบคลุมการสร้างและอัปเดตทรัพยากรด้วยไม่ใช่แค่การตอบสนอง
2. JSend - ง่ายและอาจเป็นสิ่งที่คุณทำอยู่แล้ว
3. OData JSON Protocol - ซับซ้อนมาก
4. HAL - ชอบ OData แต่ตั้งเป้าที่จะเป็นHATEOASเช่น

นอกจากนี้ยังมีรูปแบบคำอธิบาย JSON API:

• กรีดกราย
  • JSON Schema (ใช้โดยวางท่า แต่คุณสามารถใช้แบบสแตนด์อโลนได้)
• WADL ใน JSON
• Raml
• HAL เพราะHATEOASในทางทฤษฎีเป็นการอธิบายตนเอง

คู่มือ Google JSON

กลับมาตอบสนองความสำเร็จ data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

ตอบกลับข้อผิดพลาด error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

และหากลูกค้าของคุณคือ JS คุณสามารถใช้if ("error" in response) {}เพื่อตรวจสอบว่ามีข้อผิดพลาด

ฉันเดาว่ามาตรฐาน defacto ยังไม่เกิดขึ้นจริง ๆ (และอาจไม่เคยเกิดขึ้น) แต่ไม่คำนึงถึงนี่คือการใช้ของฉัน:

คำขอที่ประสบความสำเร็จ:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

คำขอล้มเหลว:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

ข้อได้เปรียบ: องค์ประกอบระดับบนสุดเหมือนกันทั้งในกรณีที่สำเร็จและผิดพลาด

ข้อเสีย: ไม่มีรหัสข้อผิดพลาด แต่ถ้าคุณต้องการคุณสามารถเปลี่ยนสถานะเป็นรหัส (สำเร็จหรือล้มเหลว) หรือ - คุณสามารถเพิ่มรายการระดับบนสุดอีกชื่อ "รหัส"

สมมติว่าคำถามของคุณเกี่ยวกับการออกแบบเว็บเซอร์ REST และแม่นยำยิ่งขึ้นเกี่ยวกับความสำเร็จ / ข้อผิดพลาด

ฉันคิดว่าการออกแบบมี 3 แบบ

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

   • ข้อดี: มันเป็นมาตรฐานอิสระจาก API ของคุณ
   • จุดด้อย: ข้อมูลน้อยลงเกี่ยวกับสิ่งที่เกิดขึ้นจริง

2. ใช้HTTP Status + json body (แม้ว่าจะเป็นข้อผิดพลาด) กำหนดโครงสร้างที่สม่ำเสมอสำหรับข้อผิดพลาด (เช่น: รหัส, ข้อความ, เหตุผล, ประเภท, ฯลฯ ) และใช้เพื่อหาข้อผิดพลาดหากประสบความสำเร็จให้ส่งคืน json ที่คาดไว้

   • ข้อดี: ยังคงมาตรฐานเมื่อคุณใช้รหัสสถานะ HTTP ที่มีอยู่และคุณส่งคืน json เพื่ออธิบายข้อผิดพลาด (คุณให้ข้อมูลเพิ่มเติมเกี่ยวกับสิ่งที่เกิดขึ้น)
   • ข้อด้อย: เอาต์พุต json จะแตกต่างกันไปขึ้นอยู่กับว่าเป็นข้อผิดพลาดหรือความสำเร็จ

3. ลืมสถานะ http (เช่นสถานะเสมอ 200) ใช้ json เสมอและเพิ่มที่รูทของการตอบสนองบูลีน responseValid และวัตถุข้อผิดพลาด (รหัสข้อความ ฯลฯ ) ที่จะถูกเติมหากมีข้อผิดพลาดเป็นอย่างอื่นฟิลด์อื่น (สำเร็จ) มีการเติมข้อมูล

   • ข้อดี: ไคลเอ็นต์จัดการเฉพาะกับเนื้อความของการตอบกลับที่เป็นสตริง json และละเว้นสถานะ (?)

   • จุดด้อย: มาตรฐานน้อย

มันขึ้นอยู่กับคุณที่จะเลือก :)

ขึ้นอยู่กับ API ฉันจะเลือก 2 หรือ 3 (ฉันชอบ 2 สำหรับ json rest apis) อีกสิ่งหนึ่งที่ฉันมีประสบการณ์ในการออกแบบ REST Api คือความสำคัญของเอกสารสำหรับแต่ละทรัพยากร (url): พารามิเตอร์, เนื้อความ, การตอบสนอง, ส่วนหัว ฯลฯ + ตัวอย่าง

ฉันขอแนะนำให้คุณใช้ Jersey (การใช้งาน jax-rs) + genson (java / json databinding library) คุณเพียงแค่วาง genson + jersey ใน classpath ของคุณและ json ได้รับการสนับสนุนโดยอัตโนมัติ

แก้ไข:

• โซลูชันที่ 2 นั้นยากที่สุดในการใช้งาน แต่ข้อดีคือคุณสามารถจัดการข้อยกเว้นได้อย่างดีและไม่เพียง แต่ข้อผิดพลาดทางธุรกิจความพยายามครั้งแรกนั้นสำคัญกว่า แต่คุณจะชนะในระยะยาว

• โซลูชัน 3 เป็นวิธีการที่ง่ายในการใช้งานทั้งฝั่งเซิร์ฟเวอร์และไคลเอนต์ แต่ก็ไม่ดีเท่าที่คุณจะต้องห่อหุ้มวัตถุที่คุณต้องการกลับมาในวัตถุตอบกลับที่มีข้อผิดพลาด responseValid +

RFC 7807: รายละเอียดปัญหาสำหรับ HTTP API ที่เป็นอยู่ในขณะนี้สิ่งที่ใกล้เราจะต้องเป็นมาตรฐานอย่างเป็นทางการ

ต่อไปนี้เป็น instagram รูปแบบ json ใช้

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

ฉันจะไม่อวดดีที่จะอ้างว่านี่เป็นมาตรฐานดังนั้นฉันจะใช้แบบฟอร์ม "ฉันชอบ"

ฉันชอบการตอบสนองสั้น ๆ (เมื่อขอรายการ / บทความที่ฉันต้องการอาร์เรย์ของบทความ JSON)

ในการออกแบบของฉันฉันใช้ HTTP สำหรับรายงานสถานะ200ส่งคืนเฉพาะเพย์โหลด

400ส่งคืนข้อความว่ามีอะไรผิดปกติกับคำขอ:

{"message" : "Missing parameter: 'param'"}

ส่งคืน404หากไม่มีโมเดล / controler / URI

หากมีข้อผิดพลาดในการประมวลผลด้านข้างของฉันฉันกลับ501ด้วยข้อความ:

{"message" : "Could not connect to data store."}

จากสิ่งที่ฉันเห็นกรอบ REST-ish ค่อนข้างน้อยมีแนวโน้มที่จะเป็นไปตามบรรทัดเหล่านี้

เหตุผล :

JSON ควรจะเป็นส่วนของข้อมูลรูปแบบก็ไม่ได้เป็นโปรโตคอลเซสชั่น แนวคิดทั้งหมดของ payloads เซสชัน verbose-ish มาจากโลก XML / SOAP และตัวเลือกที่เข้าใจผิดต่าง ๆ ที่สร้างการออกแบบที่ป่องเหล่านั้น หลังจากที่เรารู้ว่าทั้งหมดนั้นเป็นอาการปวดหัวอย่างมากจุดทั้งหมดของ REST / JSON ก็คือการจูบและเป็นไปตาม HTTP ฉันไม่คิดว่าจะมีอะไรมาตรฐานจากระยะไกลใน JSend อย่างใดอย่างหนึ่งและโดยเฉพาะอย่างยิ่งไม่ได้มี verbose มากขึ้นในหมู่พวกเขา XHR จะตอบสนองต่อการตอบกลับ HTTP หากคุณใช้ jQuery สำหรับ AJAX ของคุณ (เช่นส่วนใหญ่) คุณสามารถใช้try/ catchและdone()/ fail()callback เพื่อดักจับข้อผิดพลาด ฉันไม่เห็นว่าการห่อหุ้มรายงานสถานะใน JSON มีประโยชน์มากกว่านั้นอย่างไร

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

อย่างไรก็ตามหากมีข้อผิดพลาด (บางอย่างในครอบครัว 400) ฉันส่งคืนวัตถุข้อผิดพลาด JSON ที่มีรูปแบบที่ดี ตัวอย่างเช่นหากลูกค้าโพสต์ผู้ใช้ด้วยที่อยู่อีเมลและหมายเลขโทรศัพท์และหนึ่งในนั้นมีรูปแบบไม่ถูกต้อง (เช่นฉันไม่สามารถแทรกลงในฐานข้อมูลของฉัน) ฉันจะส่งคืนสิ่งนี้:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

บิตสำคัญที่นี่คือคุณสมบัติ "เขตข้อมูล" ต้องตรงกับเขตข้อมูล JSON ที่ไม่สามารถตรวจสอบได้ สิ่งนี้ช่วยให้ลูกค้าทราบได้อย่างแม่นยำว่าเกิดอะไรขึ้นกับคำขอของพวกเขา นอกจากนี้ "ข้อความ" ยังอยู่ในตำแหน่งที่ตั้งของคำขอ หากทั้ง "emailAddress" และ "phoneNumber" ไม่ถูกต้องอาร์เรย์ "ข้อผิดพลาด" จะมีรายการสำหรับทั้งคู่ เนื้อหาการตอบสนอง JSON 409 (ความขัดแย้ง) อาจมีลักษณะเช่นนี้:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

ด้วยรหัสสถานะ HTTP และ JSON นี้ไคลเอ็นต์มีทั้งหมดที่พวกเขาต้องการเพื่อตอบสนองต่อข้อผิดพลาดในทางที่กำหนดและไม่ได้สร้างมาตรฐานข้อผิดพลาดใหม่ที่พยายามที่จะเปลี่ยนรหัสสถานะ HTTP ให้เสร็จสมบูรณ์ หมายเหตุสิ่งเหล่านี้เกิดขึ้นสำหรับช่วง 400 ข้อผิดพลาดเท่านั้น สำหรับทุกสิ่งในช่วง 200 ฉันสามารถคืนสิ่งที่เหมาะสมได้ สำหรับฉันมันมักจะเป็นวัตถุ JSON เหมือน HAL แต่นั่นไม่สำคัญเลย

สิ่งหนึ่งที่ฉันคิดเกี่ยวกับการเพิ่มคือรหัสข้อผิดพลาดที่เป็นตัวเลขทั้งในรายการอาร์เรย์ "ข้อผิดพลาด" หรือรากของวัตถุ JSON เอง แต่จนถึงตอนนี้เราไม่ต้องการมัน

พวกเขาไม่มีข้อตกลงเกี่ยวกับรูปแบบการตอบสนองที่เหลือของยักษ์ใหญ่ซอฟต์แวร์ - Google, Facebook, Twitter, Amazon และอื่น ๆ แม้ว่าจะมีการเชื่อมโยงจำนวนมากไว้ในคำตอบข้างต้นซึ่งบางคนพยายามสร้างมาตรฐานรูปแบบการตอบสนอง

เนื่องจากความต้องการของ API นั้นแตกต่างกันมากจึงเป็นเรื่องยากที่จะให้ทุกคนเข้าร่วมและตกลงในบางรูปแบบ หากคุณมีผู้ใช้หลายล้านคนที่ใช้ API ของคุณเหตุใดคุณจึงต้องเปลี่ยนรูปแบบการตอบกลับของคุณ

ต่อไปนี้เป็นรูปแบบการตอบสนองของฉันที่ได้รับแรงบันดาลใจจาก Google, Twitter, Amazon และบางโพสต์บนอินเทอร์เน็ต:

https://github.com/adnan-kamili/rest-api-response-format

ไฟล์ Swagger:

https://github.com/adnan-kamili/swagger-sample-template

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

ชนิดของรูทโหนดนั้นขึ้นอยู่กับคุณสิ่งที่อยู่ในนั้นขึ้นอยู่กับคุณไม่ว่าคุณจะส่งเมทาดาทาพร้อมกับการตอบสนองขึ้นอยู่กับคุณไม่ว่าคุณจะตั้งค่าชนิด mime เป็นapplication/jsonหรือปล่อยให้มันtext/plainขึ้นอยู่กับคุณ ตราบใดที่คุณรู้วิธีจัดการกับเคสขอบ)

สร้างสคีมาที่มีน้ำหนักเบาตามที่คุณต้องการ
ส่วนตัวผมได้พบว่าการวิเคราะห์ติดตามและ MP3 / OGG ให้บริการและภาพแกลเลอรี่ที่ให้บริการและการส่งข้อความและเครือข่ายแพ็คเก็ตสำหรับการเล่นเกมออนไลน์และบล็อกโพสต์และบล็อกแสดงความคิดเห็นทั้งหมดมีความต้องการที่แตกต่างกันมากในแง่ของสิ่งที่เป็น ส่งและสิ่งที่ได้รับและวิธีที่ควรบริโภค

ดังนั้นสิ่งสุดท้ายที่ฉันต้องการเมื่อทำสิ่งนั้นทั้งหมดคือการพยายามทำให้แต่ละคนเป็นไปตามมาตรฐานสำเร็จรูปที่เหมือนกันซึ่งอิงกับ XML2.0 หรือ somesuch

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

JSON-RPC 2.0กำหนดรูปแบบคำขอและการตอบสนองมาตรฐานและสูดอากาศบริสุทธิ์หลังจากทำงานกับ REST API

สำหรับผู้ที่มาในภายหลังนอกเหนือจากคำตอบที่ยอมรับซึ่งรวมถึง HAL, JSend และ JSON API ฉันจะเพิ่มข้อกำหนดอื่น ๆ ที่ควรพิจารณา:

• JSON-LDซึ่งเป็นคำแนะนำ W3C และระบุวิธีสร้างเว็บเซอร์วิสที่ใช้งานร่วมกันได้ใน JSON
• Ion Hypermedia Typeสำหรับ REST ซึ่งอ้างว่าตัวเองเป็น "ไฮเปอร์มีเดียประเภท JSON ที่ใช้งานง่ายสำหรับ REST"

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

ฉันทำการวิจัยเล็กน้อยและพบว่ารูปแบบที่พบบ่อยที่สุดสำหรับการส่งคืนข้อผิดพลาด (ข้อยกเว้น) เป็นโครงสร้างของแบบฟอร์มนี้:

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

นี่เป็นรูปแบบที่เสนอโดยมาตรฐานข้อมูลOASIS OASIS ODataและดูเหมือนว่าจะเป็นตัวเลือกมาตรฐานมากที่สุดในนั้น รูปแบบนี้สอดคล้องกับข้อกำหนด JSON-RPC

คุณสามารถค้นหาไลบรารี่โอเพ่นซอร์สที่ใช้สิ่งนี้ได้ที่: Mendocino JSON Utilities ไลบรารีนี้รองรับวัตถุ JSON เช่นเดียวกับข้อยกเว้น

รายละเอียดจะกล่าวถึงในโพสต์บล็อกของฉันเกี่ยวกับการจัดการข้อผิดพลาดใน JSON REST API

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

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

นอกจากนี้เราควรตั้งค่าสถานะ 'ข้อผิดพลาด' จริงหรือไม่ จะเป็นอย่างไรถ้าฉันต้องการตอบกลับด้วยข้อผิดพลาดในการตรวจสอบความถูกต้องหลายรายการ ดังนั้นฉันคิดว่ามันมีประสิทธิภาพมากกว่าที่จะมีโหนด 'ข้อผิดพลาด' โดยที่แต่ละข้อผิดพลาดเป็นโหนดย่อยกับโหนดนั้น โดยที่ 'ข้อผิดพลาด' โหนดว่างเปล่า (นับเป็นศูนย์) จะแสดงถึง 'ความสำเร็จ'

การตอบสนองที่ดีที่สุดสำหรับ Web apis ที่นักพัฒนามือถือสามารถเข้าใจได้ง่าย

นี่คือการตอบสนอง "ความสำเร็จ"

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

นี่คือการตอบสนอง "ข้อผิดพลาด"

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}