कैसे एक सार्वजनिक एपीआई में प्रतिनिधित्व (enum) प्रकार

32

मैं एक साधारण एपीआई पर काम कर रहा हूं जिसे मैं अपने ग्राहक के लिए उपयोग करना चाहता हूं, और भविष्य में जनता के लिए खोलना चाहता हूं। मेरे पास "आइटम" ऑब्जेक्ट हैं जो अलग-अलग "प्रकार" हो सकते हैं। इस समय मेरे लिए एक C एक "टाइपफीड एनम" है:

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 को मैन्युअल रूप से संपादित करेंगे?

— जेम्स

39

तार प्रदान करें। नंबर अर्थहीन हैं। आप उन्हें अपने कोड में उपयोग नहीं करते हैं, ठीक है (आप चारों ओर enum मानों को लपेट रहे हैं, जो मूल रूप से तार हैं) - इन नंबरों का उपयोग करने के साथ उपयोगकर्ता को दंडित क्यों करें?

यदि आप संख्याओं को उजागर करते हैं तो एकमात्र प्रो - आपके लिए ये पार्स करना आसान है। लेकिन हे, जो तुम्हारी परवाह करता है। एपीआई ग्राहकों का ख्याल रखें।

यदि आप स्ट्रिंग्स प्रदान करते हैं - ग्राहकों के लिए आसान; "4 को 17 के पक्ष में चित्रित किया गया था" जैसी चीजों को कभी भी कहने की ज़रूरत नहीं होगी; आपकी ओर से थोड़ा कठिन है, लेकिन यह ठीक है।

दोनों प्रदान न करें: एक उपयोगकर्ता के रूप में, मुझे आश्चर्य करने के लिए छोड़ दिया गया है

मैं किसका उपयोग करूं? दोनों? [डॉक्स पढ़ने पर]
एक ही बात कहने के दो तरीके क्यों हैं? क्या वे सूक्ष्म रूप से भिन्न हैं? [डॉक्स पढ़ने पर]
क्या होगा अगर मैं दोनों को निर्दिष्ट करता हूं और एक बेमेल है? क्या इसकी शिकायत होगी? क्या कोई पूर्वता लेगा? कौनसा? [डॉक्स पढ़ने पर]

जैसा कि आप देख सकते हैं, आप मुझे बिना किसी कारण के बहुत सारे डॉक्स पढ़ा रहे हैं।

— Iluxa
स्रोत

मैं @iluxa से सहमत हूं

— portforwardpodcast

1

क्या होगा यदि एनम रेस्ट कॉल में इनपुट के रूप में अपेक्षित क्लास (ऑब्जेक्ट) का सदस्य है?

— स्टालियन

2

स्ट्रिंग्स।

Json की एक ताकत यह है कि यह मानव-पठनीय है। जब आउटपुट को अब से डेढ़ साल बाद डिबग करना है तो "0" आपको कुछ नहीं बताएगा।

कुछ ढांचे ऑटो-रूपांतरण भी करेंगे। यदि आप एक का उपयोग नहीं कर रहे हैं - आप अपने कोड को सूखा रखने के लिए एक कनवर्टर खुद बना सकते हैं।

यह एक वोट कास्टिंग में बदल जाता है, हालांकि।

— ईव्जेनी
स्रोत

1

बेस्ट प्रैक्टिस इस बात पर निर्भर करती है कि आपका एपीआई कौन खा रहा है। यदि आप उपभोक्ता के लिए जीवन को आसान बनाने की कोशिश कर रहे हैं, तो आपको C, JAVA, iOS, python, रूबी में नमूना कोड प्रदान करना चाहिए जो आपके एपीआई का उपभोग कर सकता है। इन रैपरों में आप एनम को शामिल कर सकते हैं, जोंस में एक इंट का उपयोग कर सकते हैं, और फिर पहले से सेट की गई ईनम के साथ किसी वस्तु में अपने जन्स को पार्स कर सकते हैं और इस ऑब्जेक्ट को यूजर्स कोड में वापस कर सकते हैं।

एक और चीज जो आप कर सकते हैं, वह दोनों प्रदान करना है। उदाहरण के लिए:

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

या आप अपने एपीआई के लिए जो सबसे अच्छा लगता है, उसके आधार पर आप टाइप, और टाइपस्ट्र का उपयोग कर सकते हैं।

और फिर अपने दस्तावेज़ में स्पष्ट रूप से बताएं कि ये बेमानी हैं और यह डेवलपर पर निर्भर है कि वह अपने आवेदन के लिए सबसे अच्छा है।

यहां देखें json: https://dev.twitter.com/docs/api/1/get/search ट्विटर पर बेमानी डेटा (आईडी और id_str) प्रदान करने का एक उदाहरण है, लेकिन ऐसा इसलिए है क्योंकि कुछ json क्लाइंट कैंट पार्स से लंबे समय तक पार्स करते हैं json में एक "संख्या" और अंकों को खोने से बचने के लिए एक स्ट्रिंग की आवश्यकता होती है

— portforwardpodcast
स्रोत