JSON API

यह क्या परोसता है

यह API सामग्री-वृक्ष का प्रतिबिंब है। बारह परंपराएँ, हर एक से आसवित सिद्धांत, उनके मूल ग्रंथ, अंतर-परंपरा तुलना-स्तर, संयोग दिक्सूचक, और स्वयं संग्रह की समीक्षा-स्थिति — सब JSON के रूप में पता-योग्य हैं। जहाँ दस्तावेज़ लंबा गद्य है, वहाँ प्रतिक्रिया उसे ऐसे फ़ील्डों में बाँटने के बजाय, जो संग्रह के पास वस्तुतः हैं ही नहीं, मार्कडाउन के रूप में ढोती है।

यह केवल-पठन है। केवल GET परोसा जाता है, हर प्रतिक्रिया सार्वजनिक है, और सामग्री CC BY-SA 4.0 के अन्तर्गत अनुज्ञप्त है।

कोई भी एंडपॉइंट अनुरोध-निकाय, हेडर या क्वेरी-पैरामीटर नहीं लेता — पथ ही पूरा अनुरोध है। वही URL सदा वही बाइट लौटाता है, और यही कारण है कि भाषा हेडर में नहीं, URL में रहती है।

आवरण

हर प्रतिक्रिया में वही तीन शीर्ष-स्तरीय कुंजियाँ होती हैं, इसलिए क्लाइंट किसी भी एंडपॉइंट के साथ एक ही तरह पेश आ सकता है, और केवल मूल URL जानते हुए पूरे वृक्ष तक पहुँच सकता है।

data

पेलोड, और एकमात्र ऐसा भाग जिसका आकार एक एंडपॉइंट से दूसरे में बदलता है। अधिकांश में एक ऑब्जेक्ट; दो संग्रहों में एक ऐरे, जो परंपराओं की और किसी एक परंपरा के मूल ग्रंथों की सूची देते हैं।

_links

संबंधित एंडपॉइंट की ओर नामित लिंक। हर एक में href होता है, और प्रायः संबंध बताने वाला rel भी।

• self — इस एंडपॉइंट का अपना पता, हर प्रतिक्रिया पर
• parent — वृक्ष में एक पग ऊपर
• html — वही सामग्री ढोने वाला मनुष्य-पठनीय पृष्ठ, प्रतिक्रिया की ही भाषा में
• alternate — मूल पर, प्रति भाषा एक: वही API नौ भाषा-संस्करणों में से हर एक में, ताकि पूरा वृक्ष URL का अनुमान लगाए बिना, केवल लिंक के अनुसरण से पहुँच में आ जाए
• _links — संग्रह की हर प्रविष्टि इनका अपना खंड ढोती है, इसलिए सूची पतों का समुच्चय भी है

_meta

हर प्रतिक्रिया में वही तीन फ़ील्ड।

• lang — इस दस्तावेज़ की भाषा — जिस वृक्ष से यह आया उसकी भाषा, हर अनुरोध पर तय की गई भाषा नहीं
• license — सामग्री की अनुज्ञप्ति, CC BY-SA 4.0
• apiVersion — API का संस्करण, अभी 1.0

OpenAPI विवरण इस ऑब्जेक्ट पर दो वैकल्पिक फ़ील्ड भी गिनाता है — एक एंटिटी टैग के लिए और एक अन्तिम-संशोधन तिथि के लिए। आज इनमें से कोई भी सेट नहीं किया जाता, इसलिए दोनों को अनुपस्थित मानें, न कि कभी-कभी छूट जाने वाले।

{
  "data": {
    "name": "Cross-Tradition Map",
    "description": "29 convergence themes, 13 held tensions, 41 preserved jewels across 12 traditions.",
    "themeCount": 27,
    "tensionCount": 13,
    "jewelCount": 41
  },
  "_links": {
    "self": {
      "href": "/api/map.json",
      "rel": "self"
    },
    "parent": {
      "href": "/api.json",
      "rel": "parent"
    },
    "convergence": {
      "href": "/api/map/convergence.json",
      "rel": "collection"
    },
    "divergence": {
      "href": "/api/map/divergence.json",
      "rel": "collection"
    },
    "jewels": {
      "href": "/api/map/jewels.json",
      "rel": "collection"
    },
    "html": {
      "href": "/en/map",
      "rel": "alternate",
      "type": "text/html"
    }
  },
  "_meta": {
    "lang": "en",
    "license": "CC BY-SA 4.0",
    "apiVersion": "1.0"
  }
}

एंडपॉइंट

तेरह रूप। इनमें से तीन परंपरा का पहचानकर्ता लेते हैं, और उन तीन में से एक ग्रंथ का पहचानकर्ता भी लेता है, इसलिए भिन्न-भिन्न URL पंक्तियों से कहीं अधिक हैं।

तेरह में से ग्यारह भाषा-उपसर्ग के अन्तर्गत भी मिलते हैं। अन्तिम स्तंभ बताता है कि कौन-से, और नीचे भाषाओं वाला खंड बताता है कि इससे क्या मिलता है और क्या नहीं।

इस पथ के नीचे और कुछ नहीं परोसा जाता। यदि कोई एंडपॉइंट यहाँ सूचीबद्ध नहीं है तो वह है ही नहीं, और मूल सूची ही प्रमाण है — वह केवल उन्हीं एंडपॉइंट से जोड़ती है जो वस्तुतः खुलते हैं।

इसे आज़माना

आरम्भ करने की जगह मूल सूची ही है — वह छोटी है, और हर दूसरा एंडपॉइंट उसी से लटका है, हर भाषा का मूल भी।

curl -s https://distill.family/api.json

OpenAPI विवरण

एक OpenAPI 3.1 दस्तावेज़ ऊपर के हर एंडपॉइंट का वर्णन करता है, साथ में आवरण और लिंक की स्कीमा का भी। उस पर कोई जनरेटर चलाएँ, या बस उसे पढ़ें।

/api/openapi.json

भाषा-उपसर्ग वाले एंडपॉइंट टेम्पलेट के रूप में छोड़ने के बजाय एक-एक भाषा करके लिख दिए गए हैं। जनरेट किया गया क्लाइंट ऐसे टेम्पलेट में मान नहीं भर सकता जिसके लिए उसके पास कोई सूची ही न हो, और वह निर्माण-जाँच भी टेम्पलेट का पीछा नहीं कर सकती जो यह सुनिश्चित करती है कि हर प्रलेखित पथ सचमुच खुलता है — इसलिए उन्हें एक-एक करके गिना देना पूरे भाषा-वृक्ष को उसी जाँच के नीचे रखता है।

इसे यहाँ किसी अन्तःक्रियात्मक एक्सप्लोरर में जान-बूझकर नहीं दिखाया गया। यह साइट ऐसी सामग्री-सुरक्षा नीति भेजती है जो स्क्रिप्ट, शैली और नेटवर्क-संपर्क केवल अपने ही ऑरिजिन से आने देती है, और सारे एक्सप्लोरर कहीं और से लोड होते हैं — इसलिए किसी एक को यहाँ जड़ने पर या तो वह चुपचाप विफल होता, या हर आगंतुक के लिए उस नीति को कमज़ोर करना पड़ता। दस्तावेज़ ले आएँ और उसे किसी ऐसे औज़ार में खोलें जिस पर आप पहले से भरोसा करते हैं।

भाषाएँ

वही एंडपॉइंट परोसने वाले दो वृक्ष हैं। इनमें विहित वृक्ष अंग्रेज़ी वाला है। दूसरा भाषा-उपसर्ग धारण करता है और साइट द्वारा समर्थित नौ भाषाओं में से हर एक के लिए एक बार बनाया जाता है।

/api/es.json

भाषा पथ का एक खंड है, कोई वार्ता नहीं। न कोई क्वेरी-पैरामीटर पढ़ा जाता है और न Accept-Language हेडर — और यह एक डिज़ाइन-निर्णय है, चूक नहीं। हर एंडपॉइंट पूर्व-रेंडर किया जाता है: हैंडलर निर्माण के समय एक ही बार चलता है, ऐसा कोई अनुरोध होता ही नहीं जिससे वार्ता की जा सके, और फिर बनी हुई फ़ाइल सबको परोस दी जाती है। जो प्रतिक्रिया हेडर के अनुसार बदल ही नहीं सकती, उसे अपनी भाषा URL में ढोनी पड़ती है, जहाँ वह पता-योग्य, लिंक-योग्य और कैश-योग्य होती है।

जो भाषा-खंड उन नौ में से नहीं है, वह 404 लौटाता है। अंग्रेज़ी को किसी दूसरी भाषा के URL के नीचे परोसना और फिर किसी कैश-स्तर को उसे वहीं टिकाए रखने देना इससे बुरा होता — भाषा को पथ में रखने का पूरा मतलब ही यह है कि पता सच बोले कि लौटा क्या।

इसे जाँचने का एक दूसरा कारण भी है। भाषा-रिज़ॉल्वर जो कुछ लौटाता है, वह संग्रह पढ़े जाते समय फ़ाइल-सिस्टम का पथ बनाने में काम आता है, इसलिए सीधे अनुरोध से लिया गया मान सामग्री-वृक्ष के बाहर की फ़ाइलें माँगने का रास्ता बन जाता। रिज़ॉल्वर कुछ भी लौटाने से पहले समर्थित भाषाओं की बन्द सूची से मिलान करता है, इसलिए उसे जैसे भी बुलाया जाए, वह ऐसा खंड नहीं दे सकता जो उस सूची में न हो। ऊपर वाला 404 ईमानदारी की बात है; यह हिस्सा सुरक्षा की।

एक स्तर बिलकुल अनूदित नहीं है। अलग-अलग मूल ग्रंथ हर जगह अंग्रेज़ी में ही हैं, क्योंकि उनका कोई अनुवाद है ही नहीं — इसलिए वे एंडपॉइंट केवल अंग्रेज़ी वृक्ष से परोसे जाते हैं, और भाषा-उपसर्ग वाला ग्रंथ-संग्रह हर प्रविष्टि को वापस उसी अंग्रेज़ी दस्तावेज़ से जोड़ता है, जो अपने विषय में यही बात दर्ज करता है।

बाकी जगह अनुवाद प्रति-वृक्ष नहीं, प्रति-दस्तावेज़ है। हर प्रतिक्रिया एक संकेतक ढोती है जो बताता है कि उसमें रखा दस्तावेज़ अनूदित है या नहीं, और जिस दस्तावेज़ का उस भाषा में अनुवाद नहीं है वह कुछ न लौटाने के बजाय अंग्रेज़ी पर लौट आता है। इसलिए URL नहीं, संकेतक पढ़ें।

और संकेतक को संकीर्ण अर्थ में पढ़ें। वह इतना दर्ज करता है कि अनुवाद मौजूद है और उसमें से कुछ भी आधारभूत खोया नहीं — शीर्षक, उद्धरण, संदर्भ और संरक्षित शब्द, सबकी उपस्थिति जाँची जाती है। वह यह दर्ज नहीं करता कि अनुवाद यथार्थ है। इस संग्रह का कोई अंश किसी मातृभाषी ने नहीं पढ़ा है। अनूदित दस्तावेज़ को सत्यापित पाठ नहीं, काम-चलाऊ प्रस्तुति मानना ही ठीक है, और मूल एंडपॉइंट यह बात अपनी ही प्रतिक्रिया में कह देता है, ताकि क्लाइंट को स्वयं पता न लगाना पड़े।

हेडर और कैशिंग

क्रॉस-ऑरिजिन अनुरोध किसी भी होस्ट से स्वीकार्य हैं, इसलिए कहीं से भी परोसा गया पृष्ठ इन्हें सीधे ला सकता है। केवल GET और OPTIONS की घोषणा की जाती है।

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

इसका उपयोग

आसवित सामग्री क्रिएटिव कॉमन्स एट्रिब्यूशन-शेयरअलाइक 4.0 (नए टैब में खुलता है) के अन्तर्गत अनुज्ञप्त है। इसका उपयोग करें, इसे उद्धृत करें, इस पर निर्माण करें — श्रेय Distill.family को दें, और जो बनाएँ उसे भी इसी तरह अनुज्ञप्त करें। शास्त्र-उद्धरण सार्वजनिक-डोमेन संस्करणों से हैं, और जहाँ किसी विशिष्ट अनुवाद पर भरोसा किया गया वहाँ पंक्ति में ही श्रेय दिया गया है।

आँकड़ों के साथ दो बातें साथ ले जाएँ। उद्धरण उन्हीं संस्करणों के सामने अक्षर-दर-अक्षर सत्यापित हैं, किन्तु बारह परंपराओं में से किसी के भी भीतर के किसी विद्वान ने इन पाठों पर स्वीकृति नहीं दी है; समीक्षा-स्थिति वाला एंडपॉइंट परंपरा-दर-परंपरा ठीक-ठीक बताता है कि यह कहाँ तक पहुँचा है।

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