واجهة JSON البرمجية

ما الذي تقدّمه

تعكس الواجهة شجرة المحتوى. فالتقاليد الاثنا عشر، والمبادئ المقطَّرة من كلٍّ منها، وكتبها المصدرية، وطبقة المقارنة العابرة للتقاليد، وبوصلة الاتحاد، وحالة مراجعة المتن نفسه — كلها قابلة للعنونة بصيغة JSON. وحيث تكون الوثيقة نثرًا مطوّلًا، تحملها الاستجابة بصيغة markdown بدل تقسيمها إلى حقول لا وجود لها في المتن أصلًا.

وهي للقراءة فقط. لا يُقدَّم إلا GET، وكل استجابة علنية، والمحتوى مرخّص بموجب CC BY-SA 4.0.

لا تأخذ أي نقطة نهاية جسم طلب ولا ترويسة ولا معامل استعلام — فالمسار هو الطلب كله. والرابط نفسه يُعيد البايتات نفسها دائمًا، وهذا أيضًا سبب وجود اللغة في الرابط لا في ترويسة.

الغلاف

لكل استجابة المفاتيح الثلاثة نفسها في المستوى الأعلى، فيستطيع العميل أن يعامل أي نقطة نهاية بالطريقة نفسها، وأن يبلغ الشجرة كلها وهو لا يعرف إلا رابط الجذر.

data

الحمولة، وهي الجزء الوحيد الذي يتغيّر شكله بين نقطة نهاية وأخرى. كائنٌ في معظمها؛ ومصفوفة في المجموعتين اللتين تسردان التقاليد وكتب تقليدٍ واحد المصدرية.

_links

روابط مسمّاة إلى نقاط نهاية ذات صلة. لكل واحد منها href، وغالبًا rel يصف العلاقة.

• self — عنوان نقطة النهاية نفسها، على كل استجابة
• parent — خطوة واحدة إلى أعلى الشجرة
• html — الصفحة المقروءة للبشر التي تحمل المحتوى نفسه، بلغة الاستجابة نفسها
• alternate — على الجذر، واحد لكل لغة: الواجهة نفسها في كل لغة من اللغات التسع، فتُبلَغ الشجرة كلها باتّباع الروابط لا بتخمين رابط
• _links — كل مدخل في مجموعة يحمل كتلته الخاصة من هذه، فالقائمة مجموعةُ عناوين أيضًا

_meta

الحقول الثلاثة نفسها في كل استجابة.

• lang — لغة هذه الوثيقة — أي لغة الشجرة التي جاءت منها، لا لغةً يُتفاوَض عليها مع كل طلب
• license — ترخيص المحتوى، CC BY-SA 4.0
• apiVersion — إصدار الواجهة، وهو حاليًّا 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"
  }
}

نقاط النهاية

ثلاثة عشر شكلًا. ثلاثة منها تأخذ مُعرِّف تقليد، وواحد من هذه الثلاثة يأخذ كذلك مُعرِّف كتاب، فعدد الروابط المتمايزة أكبر بكثير من عدد الصفوف.

إحدى عشرة من الثلاث عشرة موجودة أيضًا تحت بادئة لغوية. والعمود الأخير يبيّن أيَّها، وقسم اللغات أدناه يبيّن ما الذي يمنحه ذلك وما الذي لا يمنحه.

لا يُقدَّم شيء آخر تحت هذا المسار. فإن لم تكن نقطة النهاية مذكورة هنا فهي غير موجودة، وفهرس الجذر هو المرجع — إذ لا يحيل إلا إلى نقاط نهاية تستجيب فعلًا.

تجربتها

فهرس الجذر هو موضع البداية — فهو صغير، وكل نقطة نهاية أخرى معلَّقة به، بما في ذلك جذر كل لغة.

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

وصف OpenAPI

وثيقة OpenAPI 3.1 تصف كل نقطة نهاية أعلاه، ومعها مخطّطات الغلاف والروابط. وجّه إليها مولِّدًا، أو اقرأها فحسب.

/api/openapi.json

نقاط النهاية ذات البادئة اللغوية مكتوبة لغةً لغة بدل أن تُترك قالبًا. فالعميل المولَّد لا يستطيع أن يعوّض في قالبٍ لا قائمة لديه له، وفحص البناء الذي يؤكّد أن كل مسار موثَّق يُستجاب فعلًا لا يستطيع تتبّع قالب أيضًا — فتعدادها يُبقي شجرة اللغات كلها تحت ذلك التأكيد.

ولم تُعرَض هنا عمدًا في مستكشف تفاعلي. فهذا الموقع يرسل سياسة أمن محتوى لا تسمح بالنصوص البرمجية والأنماط واتصالات الشبكة إلا من أصله هو، والمستكشفات كلها تُحمَّل من مكان آخر — فتضمين واحدٍ منها إمّا أن يفشل بصمت وإمّا أن يعني إضعاف تلك السياسة لكل زائر. فاجلب الوثيقة وافتحها في أداة تثق بها أصلًا.

اللغات

ثمّة شجرتان تقدّمان نقاط النهاية نفسها. القانونية منهما هي الإنجليزية. والأخرى تحمل بادئة لغوية، وتُبنى مرةً لكل لغة من اللغات التسع التي يدعمها الموقع.

/api/es.json

اللغة مقطعٌ في المسار، لا مفاوضة. فلا يُقرأ معامل استعلام، ولا تُقرأ ترويسة Accept-Language — وهذا قرارٌ تصميمي لا إغفال. فكل نقطة نهاية مُصيَّرة مسبقًا: يعمل المعالج مرةً واحدة وقت البناء، بلا طلبٍ يُفاوَض عليه، ثم يُقدَّم الملف الناتج للجميع. والاستجابة التي لا يمكن أن تتغيّر بحسب ترويسة عليها أن تحمل لغتها في الرابط، حيث تكون قابلة للعنونة والربط والتخزين المؤقّت.

ومقطعٌ لغوي ليس من التسعة يُعيد 404. إذ الأسوأ أن تُقدَّم الإنجليزية تحت رابط لغة أخرى وتُترك طبقةُ تخزين مؤقّت تحفظها هناك — فمغزى وضع اللغة في المسار كله أن يقول العنوان الحقيقة عمّا عاد.

وثمّة سببٌ ثانٍ للتحقّق منه. فما يُعيده محلِّل اللغة يُستعمل لبناء مسار في نظام الملفات حين يُقرأ المتن، فقيمةٌ مأخوذة من طلبٍ مباشرةً تكون سبيلًا لطلب ملفات خارج شجرة المحتوى. والمحلِّل يقابل ما لديه بالقائمة المغلقة للغات المدعومة قبل أن يُعيد شيئًا، فلا يمكن أن يُخرج مقطعًا ليس منها مهما استُدعي. فالـ404 أعلاه شأنه الأمانة؛ وهذا الجزء شأنه السلامة.

طبقةٌ واحدة غير مترجَمة البتّة. فالكتب المصدرية المفردة بالإنجليزية في كل مكان، لأنه لا وجود لترجمةٍ لها — فتُقدَّم تلك النقاط من الشجرة الإنجليزية وحدها، ومجموعة الكتب ذات البادئة اللغوية تربط كل مدخل بالوثيقة الإنجليزية، وهي وثيقة تُقرّ بذلك عن نفسها.

وفيما عدا ذلك، الترجمة لكل وثيقة لا لكل شجرة. فكل استجابة تحمل علامة تقول أكانت الوثيقة التي فيها مترجَمة أم لا، والوثيقة التي لا ترجمة لها بتلك اللغة تعود إلى الإنجليزية بدل ألا تُعيد شيئًا. فاقرأ العلامة لا الرابط.

واقرأ العلامة قراءةً ضيّقة. فهي تسجّل أن ترجمةً موجودة وأن شيئًا حاملًا لم يُفقَد منها — إذ تُفحَص العناوين والاقتباسات والاستشهادات والمصطلحات المحفوظة كلها من جهة الحضور. لكنها لا تسجّل أن الترجمة دقيقة. ولم يراجع أيُّ ناطقٍ أصلي شيئًا من هذا المتن. والأولى أن تُعامَل الوثيقة المترجَمة بوصفها صياغة صالحة للاستعمال، لا نصًّا مُتحقَّقًا منه، ونقطةُ الجذر تقول ذلك في استجابتها هي بدل أن تترك العميل يكتشفه.

الترويسات والتخزين المؤقّت

الطلبات العابرة للأصول مسموحة من أي مضيف، فتستطيع صفحة تُقدَّم من أي مكان أن تجلب هذه مباشرةً. ولا يُعلَن إلا عن GET وOPTIONS.

الاستجابات قابلة للتخزين المؤقّت خمس دقائق في المتصفّح وساعةً في ذاكرة مؤقّتة مشتركة. وهي ملفات ساكنة خلف خادم ملفات ساكن يرسل مع كل واحدة منها وسم كيان ضعيفًا، فتعمل الطلبات الشرطية.

استعمالها

المحتوى المقطَّر مرخّص بموجب المشاع الإبداعي: نَسب المُصنَّف - الترخيص بالمثل 4.0 (يُفتح في تبويب جديد). استعمله، واقتبس منه، وابنِ عليه — وانسبه إلى Distill.family، ورخِّص ما تبنيه بالطريقة نفسها. واقتباسات النصوص المقدّسة مأخوذة من طبعات في الملكية العامة، منسوبةً داخل النص حيث اعتُمدت ترجمة بعينها.

أمران يُحمَلان مع البيانات. الاقتباسات مُتحقَّق منها محرفًا محرفًا في مقابل تلك الطبعات، لكن لم يُصادق على هذه القراءات باحثٌ من داخل أيٍّ من التقاليد الاثني عشر؛ ونقطة حالة المراجعة تقول أين يقف ذلك بالضبط، تقليدًا تقليدًا.

والموقف متبنّى، لا محايد. فالتقاليد تُعامَل هنا بوصفها رؤًى جزئية يُحتمل أن يُكمّل بعضها بعضًا، وهو ما يرفضه معظمها. وكل ما يُبنى على هذه البيانات يرث ذلك الاختيار، فالأولى إعادة ذكره لا تمريره بصمت.