ממשק ה-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, והרשו את מה שתבנו באותו אופן. ציטוטי כתבי הקודש לקוחים ממהדורות שברשות הרבים, ומיוחסים בגוף הטקסט במקום שבו הסתמכנו על תרגום מסוים.

שני דברים שכדאי לשאת יחד עם הנתונים. הציטוטים מאומתים תו אחר תו מול אותן מהדורות, אבל אף חוקר מתוך אחת משתים-עשרה המסורות לא אישר את הקריאות הללו; נקודת הקצה של מצב הסקירה מדווחת בדיוק היכן הדבר עומד, מסורת אחר מסורת.

ונקודת המבט מוצהרת, לא ניטרלית. המסורות נתפסות כאן כתפיסות חלקיות שעשויות להשלים זו את זו, ורובן דוחות זאת. כל דבר הנבנה על הנתונים האלה יורש את הבחירה הזו, ולכן מוטב לחזור ולומר אותה מאשר להעביר אותה הלאה בשתיקה.