วิธีการแสดง (enum) ประเภทใน API สาธารณะ

32

ฉันกำลังทำงานกับ API อย่างง่ายที่ฉันต้องการใช้สำหรับลูกค้าของตัวเองและเพื่อเปิดให้ประชาชนในอนาคต ฉันมีวัตถุ "รายการ" ซึ่งสามารถมี "ประเภท" ที่แตกต่างกัน ประเภทคือ C "typedef enum" ในขณะที่ฉันมี:

typedef enum {
    ItemTypeBool,
    ItemTypeNumber,
    ItemTypeDate,
} ItemType;

(ฉันอาจเพิ่มบางอย่างในอนาคต)

ฉันสงสัยว่าฉันควรจะถ่ายโอนมันเป็นจำนวนเต็มหรือตามที่กำหนดไว้ "สตริง" JSON จะเป็น:

สำหรับจำนวนเต็ม:

{
  "name": "The name",
  "type": 0,
   ...
}

สำหรับสตริง:

{
  "name": "The name"
  "type": "boolean"
   ...
}

ฉันสงสัยว่ามีวิธีปฏิบัติที่ดีที่สุดสำหรับสิ่งนี้หรือไม่ การรักษาจำนวนเต็มจะลดความซับซ้อนของรหัสเล็กน้อยและลดแบนด์วิดธ์ แต่สตริงจะง่ายขึ้นสำหรับนักพัฒนาที่จะจำ ฉันจำได้ว่าฉันทำงานในโครงการและฉันต้องจำ 1 = ภาพ, 2 = เสียง, 3 = html, ... ซึ่งไม่สมเหตุสมผลจริง ๆ

ดังนั้นฉันขอให้คุณถ้าคุณรู้ด้านอื่น ๆ ที่ฉันควรพิจารณา

api patterns-and-practices enum

— มั๊ย
แหล่งที่มา

คุณคาดหวังให้ผู้ใช้แก้ไข JSON ด้วยตนเองบ่อยครั้งหรือไม่?

— James

39

จัดเตรียมสตริง ตัวเลขไม่มีความหมาย คุณไม่ได้ใช้มันในรหัสของคุณใช่ไหม (คุณกำลังห่อค่า enum รอบ ๆ ซึ่งเป็นสตริง) - ทำไมต้องลงโทษผู้ใช้ที่ต้องใช้ตัวเลขเหล่านี้

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

หากคุณให้สตริง - ง่ายสำหรับลูกค้า; ไม่จำเป็นต้องพูดถึงสิ่งต่าง ๆ เช่น "4 ถูกคัดค้านเพราะเห็นด้วย 17"; การแยกวิเคราะห์ในนามของคุณยากขึ้นเล็กน้อย แต่ก็ไม่เป็นไร

อย่าให้ทั้งสองอย่าง: ในฐานะผู้ใช้ฉันเหลือที่จะสงสัย

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

อย่างที่คุณเห็นคุณมีให้ฉันอ่านเอกสารจำนวนมากโดยไม่มีเหตุผล

— iluxa
แหล่งที่มา

ฉันเห็นด้วยกับ @iluxa

— portforwardpodcast

1

เกิดอะไรขึ้นถ้า enum เป็นสมาชิกของคลาส (วัตถุ) ที่คาดว่าจะเป็นอินพุตในการพักสาย?

— พ่อม้า

2

เงื่อนไข

หนึ่งในจุดแข็งของ Json คือมนุษย์สามารถอ่านได้ เมื่อทำการดีบั๊กเอาต์พุตครึ่งปีนับจากนี้ "0" จะไม่บอกอะไรเลย

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

แม้ว่าจะเป็นการลงคะแนนเสียง

— Evgeni
แหล่งที่มา

1

แนวปฏิบัติที่ดีที่สุดขึ้นอยู่กับว่าใครใช้ API ของคุณ หากคุณพยายามทำให้ชีวิตของผู้บริโภคง่ายขึ้นคุณควรให้โค้ดตัวอย่างใน C, JAVA, iOS, python, ruby ที่สามารถกิน api ของคุณได้ ใน wrappers เหล่านี้คุณสามารถรวม enum ใช้ int เป็น json แล้วก็แยก json ของคุณเป็นวัตถุที่มี enum ตั้งไว้แล้วและส่งคืนวัตถุนี้ไปยังรหัสผู้ใช้

สิ่งที่คุณสามารถทำได้ก็คือให้ทั้งสองอย่าง เช่น:

{
  "name": "The name",
  "typeId": 0,
  "type": "ItemTypeBool"
   ...
}

หรือคุณสามารถใช้ประเภทและ typeStr ขึ้นอยู่กับสิ่งที่ดูดีที่สุดสำหรับ API ของคุณ

และระบุไว้อย่างชัดเจนในเอกสารของคุณว่าสิ่งเหล่านี้ซ้ำซ้อนและขึ้นอยู่กับนักพัฒนาที่จะเลือกสิ่งที่ดีที่สุดสำหรับการสมัคร

ดู json ที่นี่: https://dev.twitter.com/docs/api/1/get/search Twitter มีตัวอย่างของการให้ข้อมูลที่ซ้ำซ้อน (id และ id_str) แต่นี่เป็นเพราะลูกค้า json บางคนไม่สามารถแยก ints ยาวจาก "ตัวเลข" ใน json และต้องการสตริงเพื่อหลีกเลี่ยงการสูญเสียตัวเลข

— portforwardpodcast
แหล่งที่มา