दस्तावेज़ और संस्करण

दस्तावेज़ किसी एक API का होस्ट किया गया रूप है। यह आपके संगठन का हिस्सा होता है और किसी प्रोजेक्ट में भी रखा जा सकता है। इसे बार-बार ओवरराइट करने के बजाय समय के साथ नए संस्करण जोड़े जाते हैं।

पदानुक्रम

Organization -> Project -> Document -> Versions

दस्तावेज़ सीधे संगठन में या किसी प्रोजेक्ट के अंदर बनाए जा सकते हैं। उनकी सूची प्रोजेक्ट और संगठन, दोनों स्तरों पर उपलब्ध होती है।

स्थिति का जीवनचक्र

दस्तावेज़ की चार स्थितियाँ हो सकती हैं:

स्थिति	अर्थ	सार्वजनिक सेवाएँ
ACTIVE	सक्रिय	डॉक्यूमेंटेशन और MCP उपलब्ध रहते हैं, बशर्ते उन्हें अलग-अलग सक्षम किया गया हो
PAUSED	अस्थायी रूप से रोका गया	सार्वजनिक सेवाएँ उपलब्ध नहीं होतीं
ARCHIVED	सुरक्षित रखा गया, लेकिन वर्तमान नहीं	उपलब्ध नहीं कराया जाता
DELETED	तार्किक रूप से हटाया गया	उपलब्ध नहीं कराया जाता

ये स्थिति परिवर्तन अनुमत हैं:

pause:    ACTIVE  -> PAUSED
resume:   PAUSED  -> ACTIVE
archive:  ACTIVE / PAUSED -> ARCHIVED
restore:  ARCHIVED -> ACTIVE
delete:   ACTIVE / PAUSED / ARCHIVED -> DELETED

दस्तावेज़ को अस्थायी रूप से ऑफ़लाइन करके फिर चालू करने का सबसे तेज़ तरीका उसे रोकना है। संग्रहित करने पर इतिहास सुरक्षित रहता है, लेकिन दस्तावेज़ वर्तमान नहीं माना जाता। हटाना तार्किक होता है, इसलिए मूल डेटा तुरंत नष्ट नहीं होता।

संस्करण अपरिवर्तनीय होते हैं

स्पेसिफ़िकेशन बदलने पर नया संस्करण बनता है। पुराने संस्करण को कभी बदला नहीं जाता:

v1 -> v2 -> v3 -> v4

हर संस्करण में यह जानकारी दर्ज होती है:

• ऑब्जेक्ट स्टोरेज में फ़ाइल की स्टोरेज कुंजी;
• SHA-256 चेकसम;
• सामग्री का प्रकार, आकार और बनाए जाने का समय।

इससे इतिहास रखना, पुराने संस्करण पर लौटना, बदलावों की तुलना करना और किसी खास संस्करण के लिए डॉक्यूमेंटेशन तथा MCP दोबारा बनाना संभव होता है।

वर्तमान और निश्चित संस्करण वाले लिंक

• वर्तमान दस्तावेज़ का लिंक हमेशा सबसे नए संस्करण पर जाता है;
• निश्चित संस्करण का लिंक एक खास संस्करण पर जाता है; पाठक के लिए उसकी सामग्री अपने-आप नहीं बदलती।

जब अपरिवर्तनीय संदर्भ चाहिए, जैसे रिलीज़ नोट या कॉन्ट्रैक्ट में, तब निश्चित संस्करण वाला लिंक इस्तेमाल करें। हमेशा सबसे नया संस्करण दिखाना हो तो वर्तमान दस्तावेज़ का लिंक इस्तेमाल करें।

स्रोत

सामग्री एक अलग स्रोत परत से आती है, इसलिए दस्तावेज़ का मॉडल सीधे अपलोड या Git से बँधा नहीं होता।

• अपलोड — सीधे फ़ाइल जोड़ें;
• Git — URL, ब्रांच और फ़ाइल पाथ देकर रिपॉज़िटरी जोड़ें।

Git स्रोत में दर्ज रहता है कि सिंक सक्षम है या नहीं और पिछली बार कब हुआ था। आप ये काम कर सकते हैं:

• रिपॉज़िटरी जोड़ें: रिपॉज़िटरी का URL और फ़ाइल पाथ ज़रूरी हैं; ब्रांच वैकल्पिक है;
• ज़रूरत पड़ने पर सिंक करें: सबसे नई सामग्री को नए संस्करण के रूप में प्राप्त करें।

स्रोत का मेटाडेटा दस्तावेज़ के साथ रहता है। इसलिए आप हमेशा जान सकते हैं कि दस्तावेज़ अपलोड से आया है या रिपॉज़िटरी से, और आख़िरी सिंक भी देख सकते हैं।

स्टोरेज

असली फ़ाइलें ऑब्जेक्ट स्टोरेज में संगठन/दस्तावेज़/संस्करण के क्रम में रहती हैं। डेटाबेस में केवल मेटाडेटा रहता है: स्टोरेज कुंजी, चेकसम, सामग्री का प्रकार और आकार। डिफ़ॉल्ट रूप से फ़ाइलें स्टोरेज से सीधे सार्वजनिक रूप से नहीं पढ़ी जा सकतीं; सार्वजनिक ऐक्सेस दस्तावेज़ के प्रकाशन रूट से होता है।

इसका फ़ायदा

अपरिवर्तनीय संस्करण और तार्किक रूप से हटाने की सुविधा से आप इतिहास खोए बिना तेज़ी से बदलाव कर सकते हैं। जिस दस्तावेज़ को बंद रखना था, उसके गलती से उपलब्ध हो जाने का जोखिम भी घटता है। अस्थायी रुकावट के लिए रोकें, लंबे समय तक रखने के लिए संग्रहित करें और स्थिर संदर्भ चाहिए तो निश्चित संस्करण वाले लिंक दें।

संबंधित: उपलब्ध कराए गए ऑपरेशन, ऐक्सेस कंट्रोल, कस्टम डोमेन।