Presentation API

למה אני צריך את זה?

אתם פה כי אתם כבר ביצעתם חיפוש ואתם יודעים שאתם רוצים לקבל פריט מסוים (או יותר - במקרה זה אתם תתשאלו את ה-API הזה מספר פעמים).

אם אתם לא בטוחים איך עובד כל התהליך - חזרו לעמוד הבית ועיינו בתרשימים שם.

תפקיד ה-API

ממשק זה מקבל כקלט פרמטר של מזהה הפריט/הרשומה (Record ID) ומחזיר פלט בפורמט JSON-LD שמהווה את "תעודת הזהות", או ה-Manifest, של הרשומה שאותה אתם מבקשים.

הממשק יפורט בקיצור להלן. תעוד מפורט נמצא באתר התקן: http://iiif.io/api/presentation/2.1

קלט

http://iiif.nli.org.il/IIIFv21/DOCID/{identifier}/manifest

identifier

שדה זה מכיל את מזהה הרשומה, לדוגמה NNL_MAPS_JER002366843.

פלט

הפלט הוא JSON שיכיל את סוגי המידע הבאים:

• שדות מידע ותיאור על הרשומה
• מידע על זכויות יוצרים
• רשימה של ההעתקים הדיגיטליים של הרשומה (נקרא גם Intellectual Document, נמצא בתגית Sequence)
  כל Sequence מכיל מערך של פריטי התוכן השונים (תגית Canvas) שיש בפריט.
  
  דוגמאות:
• פריט הוא ספר, Canvas הוא דף מהספר
• פריט הוא אלבום מוזיקה, Canvas הוא שיר אחד מהאלבום
• פריט הוא אלבום תמונות, Canvas הוא תמונה אחת מהאלבום

במקרה של שגיאה, תקבלו חיווי שגיאה - HTTP Code 404 אם הפריט לא קיים או HTTP Code 403 אם אסורה הגישה לפריט בשל מגבלת זכויות יוצרים וכו'.
בגוף התשובה יהיה XML בפורמט הבא (דוגמה ל-HTTP 404):

שדות מידע ותיאור על הרשומה

שדות עיקריים בשימוש:

• label - כותרת הפריט
• Description - תיאור הפריט
• metadata - יתר המידע על הפריט מיוצג ע"י מערך של איברים מורכבים, אשר כל אחד מהם הוא צמד ערכים: שם שדה וערך השדה. לדוגמה:
• {
  "label":"Creator",
  "value":"The National Library of Israel"
  },

מידע על זכויות יוצרים

המידע על זכויות יוצרים כולל מספר שדות חשובים שיש לקרוא ולרנדר בהתאם לקבוע בתקן.
התקן מפרט את ההתנהגות כאן:
http://iiif.io/api/presentation/2.1/#rights-and-licensing-properties

• attribution - טקסט המהווה קרדיט לארגון המספק את המידע. חובה להציגו ברמת רשומת הפריט.
• license - שדה זה מתייחס למגבלות זכויות יוצרים ומגבלות חוזיות נוספות. השדה מכיל קישור לעמוד אודות תנאי השימוש בתמונה. שימו לב כי תנאי השימוש אינם זהים ביחס לכל הפריטים. למשל: השימוש בפריט עשוי להיות מוגבל לשימוש למטרות לא מסחריות בלבד או שימוש לצרכי הוראה ומחקר בלבד. במקרים אחרים ייתכן כי לא תחול מגבלה כלשהי על השימוש בפריט. על המשתמש לבדוק שהשימוש המבוקש על ידו בפריט תואם את תנאי השימוש. כמו כן יש להציג את הקישור לתנאי השימוש למשתמשי הקצה כך שיהיה לחיץ לגלישה.
• logo - סמליל הארגון המספק את הפריט.

ב-Image API תחת Image Information Service ישנם שדות בשמות זהים אך עם משמעות מעט שונה.

Sequence

Sequence הוא העתק דיגיטלי של פריט השייך לרשומה שביקשתם.
כל Sequence מכיל את רשימת פריטי התוכן השונים (Canvases) שיש בפריט באופן סדור (כלומר, יש חשיבות לסדר הפריטים).

שדות המידע הם:

• id - מזהה ייחודי של ה-Sequence
• label - השם או הכותר של הפריט
• type - תמיד יכיל Sequence
• Canvases - מערך של כל ה-Canvases (ראו הסבר על תגית Canvas למטה)

עפ"י התקן, במקרה ויש יותר מ-Sequence אחד, רק הראשון יופיע במסמך עם הפירוט של כל ה-Canvases.
כל Sequence נוסף יופיע באופן מקוצר, רק עם שלושת השדות id, label, type ומאחר ובפרמטר id מופיע ה-URI של ה-Sequence. כאשר ניגשים אל URI של Sequence מקבלים את ה-Sequence המלא עם רשימת ה-Canvases.
יש לציין כי אין זה מקרה שכיח! לרוב יש Sequence אחד לפריט.

Canvas

מערך של Canvases נמצאת בתוך Sequence. כל Canvas מכיל מספר שדות חשובים, כמו:

• label - הכותרת של הדף (לדוגמה, "עמוד מס' 6", "מפות ישראל - גליון העיר עכו")
• מימדים Width/Height - כדי לעזור ל-viewer לחשב את הפרופורציות ולמקם את ההצגה של הדף באופן אופטימלי על המסך של המשתמש.
• במידה ומדובר בתמונה, קישור ל-Image API (תחת מערךImages)
• במידה ומדובר בוידאו או שמע, קישור ל-Audio/Video API (תחת מערך OtherContent)

כל image ברשימת ה-images מכיל אובייקט בשם Resource הכולל את מזהה המשאב שיש לציין בפנייה אל ה-Image API. בנוסף, ה-Resource כולל אובייקט Service שמכיל ב-id@ שלו את ה-Base URI לגישה ל-Image API.
להלן דוגמה לאובייקט Image שנמצא במערך ה-Images:

{
       "@id": "FL42848044",
       "@type": "oa:Annotation",
       "motivation": "sc:painting",
       "on": "http://iiif.nli.org.il/IIIFv21/FL42848044",
       "resource": {
           "@id": "http://iiif.nli.org.il/IIIFv21/FL42848044/full/max/0/default.jpg",
           "@type": "dctypes:Image",
           "label": "01 North",
           "format": "image/jpeg;",
           "service": {
               "@context": "http://iiif.io/api/image/2/context.json",
               "@id": "http://iiif.nli.org.il/IIIFv21/FL42848044",
               "label": "01 North",
               "profile": "http://iiif.io/api/image/2/level1.json"
           },
           "height": 6616,
           "width": 9071
       }
   }

Range

מבנה זה, הממוקם הירארכית תחת structures ב-Manifest, מפרט את הייצוגים השונים (Representations) שיש ל-Sequence. כל ייצוג מפנה לרשימת כל ה-Canvases ששייכים לו.
בפועל, ברוב המקרים יש Representation יחיד!

• Sequence הוא אלבום מוזיקה
• לאלבום ישנם 2 ייצוגים (Representations)
• שירים באורך מלא
• דגימות של 30 שניות ראשונות מהשיר
• בכל Representation יש מערך בשם members עם הפנייה לכל כל 16 השירים (למעשה, הפנייה ל-Canvases באמצעות ה-URI שלהם, כאשר ה-Canvases עצמם מוגדרים תחת ה-Sequence).
  בפועל, תחת Sequence תמצאו את כל 32 השירים, כאשר החלוקה ביניהם (2 ייצוגים - Representations) מתבצעת באמצעות ה-Range.

דוגמאות שימוש

קישור ל-Manifest לדוגמה:

http://iiif.nli.org.il/IIIFv21/DOCID/NNL_MAPS_JER002366843/manifest