הנחיות תאימות לאחור

בכל בקשה מ-YouTube Data API אפשר לציין את גרסת ה-API שבאמצעותה המערכת של YouTube תטפל בבקשה. אם בקשה לא מציינת גרסת API, המערכת של YouTube תשתמש בגרסה הנתמכת הישנה ביותר של ה-API כדי לטפל בבקשה. הגרסה הישנה ביותר שנתמכת היא כרגע 1. חשוב לשים לב למאפיינים הבאים של מספרי הגרסאות של ה-API:

  • יכול להיות שמערכת YouTube תפיץ עדכונים לגרסת API ספציפית שעבורה לא מוקצה מספר גרסה חדש. העדכונים האלה, שתואמים לאחור, יכולים לכלול תכונות אופציונליות של ה-API, תיקוני באגים או שניהם.

  • הרחבה של מספר גרסת ה-API מזהה גרסה שמכילה שינויים שאינם תואמים לגרסאות קודמות של ה-API.

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

  • ההנחיות מזהות פונקציונליות של API שעשויה להשתנות גם אם לא תשנה את גרסת ה-API שבה יש להשתמש כדי לטפל בבקשות שלך ל-API. הקוד שלך אמור לטפל בשינויים אלה ללא שבירה. לדוגמה, אם מערכת YouTube מוסיפה תגי XML חדשים לתגובות API, הקוד אמור להתעלם מהתגים האלה.

  • ההנחיות גם מגדירות פונקציונליות ל-API שב-YouTube לא מתכוונים לשנות בעת עדכון גרסת API ספציפית. במילים אחרות, סביר להניח שהפונקציונליות הזו תשתנה רק אם מערכת YouTube תפיץ גרסת API חדשה והקוד שלכם לא צריך לבצע שינויים כאלה.

מידע על המסמך הזה

המסמך הזה כולל את הקטעים הבאים:

  • הקטע בקשות API מגדיר הנחיות תאימות לאחור הקשורות לכותרות של בקשות HTTP, פרמטרים של בקשות API, שמות של רכיבי XML (כפי שהם מופיעים בבקשות API) ובקשות ל-API שנוצרו בצורה לא תקינה.

  • הקטע תגובות API מגדיר הנחיות תאימות לאחור הקשורות לשמות של רכיבי XML (כפי שהם מופיעים בתגובות API) ואת הסדר שבו תגים ומאפיינים של XML מופיעים בתגובות API.

  • בקטע שיטות מומלצות מפורטות המלצות לשילוב ה-API של YouTube עם אפליקציית הלקוח שלכם.

בקשות API

פונקציונליות שלא מיועדת לשינוי

  • פרמטרים קיימים של בקשה.

  • ערכי פרמטרים קיימים לפרמטרים שיש להם ערכים ממוספרים או המשמעויות של ערכי הפרמטרים האלה.

  • שמות של רכיבי XML שנעשה בהם שימוש בבקשות API POST (insert) או ב-PUT (עדכון).

  • קבוצת הכותרות של בקשות HTTP הנדרשות לכל סוג של בקשת API. המשמעות של ההנחיה הזו היא שהמערכת של YouTube לא מתכוננת להוסיף כותרות נדרשות של בקשות HTTP, או לשנות את הכותרות האופציונליות של בקשות נדרשות.

  • התעלמות מפרמטרים שאינם נתמכים בבקשת API, אלא אם הבקשה משתמשת בפרמטר strict. הפרמטר הזה מורה ל-YouTube לדחות בקשת API שמכילה פרמטרים לא חוקיים של בקשה.

פונקציונליות שעשויה להשתנות

  • יכול להיות שהמערכת של YouTube תוסיף פרמטרים אופציונליים של בקשה.

  • המערכת של YouTube עשויה להוסיף ערכים חדשים לפרמטרים קיימים שיש להם קבוצות ערכים ממוספרות.

  • המערכת של YouTube יכולה לדחות כל בקשה שבה פרמטרים חוקיים מכילים ערכי פרמטר לא חוקיים. כתוצאה מכך, בקשות שנוצרו באופן שגוי שהתקבלו עקב ניתוח גמיש מדי עשויות להידחות, אם לוגיקת הניתוח תוקנה.

  • יכול להיות שהמערכת של YouTube תוסיף כותרות אופציונליות של בקשות HTTP.

  • יכול להיות שמערכת YouTube תשנה את המידע שהיא שומרת (מאחסן) במהלך הוספה או עדכון של משאב. עם זאת, החלטה זו לא תשפיע ולא תדרוש שינויים בתחביר של בקשות ה-API התואמות.

  • המערכת של YouTube עשויה לשנות את קבוצת הקטגוריות הניתנות לעיון או את קבוצת הקטגוריות שניתן להקצות להן סרטונים חדשים שהועלו.

  • תמיד אפשר להסיר או לשנות פונקציונליות שלא מתועדת.

תגובות API

פונקציונליות שלא מיועדת לשינוי

  • שמות של תגי XML קיימים.

  • שימוש במפרט ה-RSS של המדיה כדי לקבוע את סדר הרכיבים שמוגדרים במפרט ושמופיעים מספר פעמים ברשומת הפיד. לדוגמה, אם רשומה מכילה מספר תגי <media:thumbnail>, הם מסודרים לפי חשיבות.

  • ערך המאפיין term של התג <category> שמזהה את סוג הפריט שמתואר בפיד או בהזנת הפיד. בתוך התג <feed> או <entry>, התג <id> מציין את המשאב הייחודי שמזוהה על ידי הערך, ותג <category> מציין את סוג המשאב שמתואר על ידי הערך. בתג <category> הזה, הערך של מאפיין הסכמה הוא http://schemas.google.com/g/2005#kind, והערך של המאפיין 'מונח' מציין אם הרשומות בפיד מתארות סרטונים, קישורים לפלייליסטים, מינויים, אנשי קשר או כל סוג אחר של ישות.

פונקציונליות שעשויה להשתנות

  • המערכת של YouTube עשויה להוסיף תגי XML חדשים לתגובות API.

  • המערכת של YouTube עשויה להוסיף מאפיינים חדשים לתגי XML קיימים.

  • ייתכן שתגי API קיימים יחזרו על עצמם עם ערכים שונים. לדוגמה, מערכת YouTube יכולה להוסיף תג <media:restriction> חדש עם ערך type שונה או תג <media:credit> חדש עם scheme ו-role שונים.

  • סדר התגים והמאפיינים של XML בתגובת ה-API עשוי להשתנות.

  • אפשר להסיר תגי צאצא אופציונליים מתגובות ה-API.

  • תמיד אפשר להסיר או לשנות פונקציונליות שלא מתועדת.

שיטות מומלצות

  • אפשר להשתמש בערך התג <id> כדי לזהות רשומה.

  • אפשר ללחוץ על הקישור self כדי לאחזר רשומה.

  • אפשר להשתמש בקישור edit כדי לערוך או לעדכן רשומה.

  • אפשר להשתמש בערך התג <yt:videoid> לרשומת סרטון כדי להשיג את הערך שמשמש את YouTube לזיהוי ייחודי של הסרטון. אין לנתח את מזהה הווידאו מקישור.

  • יש להשתמש בכתובות ה-URL המזוהות בתגים <link>, <content> ו-<gd:feedLink> כדי לנווט בין הפידים. YouTube תומך במספר מוגבל של כתובות URL שניתן ליצור באופן מהימן כדי לאחזר פידים ספציפיים. פרט לכתובות ה-URL של הפידים, שמפורטות בהמשך, אין ליצור כתובות URL של פידים משלכם כי הן עלולות להפסיק לעבוד באופן בלתי צפוי.

    • /פידים/api/videos/<videoid>
    • /feeds/api/users/default
    • /feeds/api/users/default/uploads
    • /feeds/api/users/default/favorites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/playlists
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (מידע נוסף זמין במדריך העזר)

  • אין לנסות לנתח מזהים מספריים או אלפאנומריים מכתובות URL בתגובת API. תגובות ה-API כוללות תגים ספציפיים למזהים שמקשרים למשאבים באתר YouTube, כמו מזהי סרטונים (<yt:videoid>) ושמות משתמשים (<name> ו-<media:credit>).)

  • אם תשלחו בקשת API להוספה (POST) או לעדכון (PUT), יש להשתמש בתגובת ה-XML לבקשה הזו, כדי לקבוע אילו ערכי תגים בבקשה נשמרו ב-YouTube בפועל. כפי שמצוין בהנחיות התאימות לאחור עבור בקשות API, YouTube עשוי לשנות את המידע שנשמר (בחנויות) במהלך הוספה או עדכון של משאב. פירוש הדבר הוא שהמערכת עשויה להתעלם מחלק מהתגים בבקשה.

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

    הדוגמה הבאה ממחישה את השיטה המומלצת הזו:

    1. האפליקציה שלך מאפשרת למשתמש לעדכן תיאור של סרטון.
    2. האפליקציה שלך מאחזרת את רשומת הסרטון באמצעות ה-API, אך אינה מזהה אחד מהתגים ברשומה.
    3. המשתמש משנה את תיאור הסרטון.
    4. האפליקציה שלך צריכה לשלוח רשומת וידאו מלאה בחזרה ל-API. הערך צריך לכלול את התג הלא מזוהה משלב 2. אחרת, ייתכן שהערך הזה יימחק.

  • לפני שמנסים להציג ערך של תג, חשוב לוודא שהתג קיים ושהוא מכיל ערך שאינו אפס.

  • כפי שצוין למעלה, יכול להיות שמערכת YouTube תוסיף ערכים חדשים לתגים או למאפיינים קיימים שיש להם קבוצות ערכים ממוספרות. ככלל, הקוד צריך לנתח את הערכים של רכיבי XML שיש להם קבוצות ערכים ממוספרות, ולאחר מכן להגדיר פעולות המתאימות לערכים האלה. מומלץ לעשות זאת גם אם ערך אחד בלבד נספר עבור הרכיב.

    לדוגמה, התג <media:credit> מזהה את הבעלים של סרטון. הערך היחיד שמתועד עבור המאפיין role של התג הוא uploader, דבר שמצביע על כך שהסרטון הועלה על ידי שותף של YouTube. לפי השיטה המומלצת הזו, האפליקציה שלכם צריכה לאמת שהערך של המאפיין role של התג הוא אכן uploader לפני שמגדירים את המשתמש התואם כבעלים של הסרטון. (אמצעי זהירות זה מבטיח שהקוד שלך לא יזהה במדויק בעלים של סרטון אם מערכת YouTube מוסיפה סוגים אחרים של קרדיטים – למשל במאי – לסרטון).

    • אם לתג יש קבוצת ערכים שנספרת ואתם לא מזהים את הערך של התג הזה, אפשר להתעלם מה-<entry> המלא שבו התג מופיע.

    • יש להתעלם מפיד של מינויים אם אינכם מזהים את הערך של המאפיין term בתג <category> עם ערך המאפיין scheme של http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. התג הספציפי הזה מזהה את סוג המינוי המזוהה לפי הרשומה. אם האפליקציה לא מזהה את סוג המינוי, היא לא אמורה להציג מידע על הרשומה הזו.

    • אם לכל מאפיין אחר יש קבוצת ערכים ממוספרת ואתם לא מזהים את הערך של המאפיין הזה, אתם יכולים להתעלם מהתג שבו המאפיין מופיע.

  • קוד האפליקציה שלך אמור לקבל הודעת yt:error בכל עת. אם הפעולה של ממשק ה-API תיכשל, האפליקציה שלך צריכה לזהות את השגיאה ולהציג למשתמש מסר משמעותי.

  • YouTube עשוי להוסיף קטגוריות חדשות לסיווג סרטונים בכל שלב. המערכת של YouTube עשויה גם לעדכן או להוציא משימוש קטגוריות קיימות. אפשר לאחזר קובץ קטגוריות נוכחי בכתובת http://gdata.youtube.com/schemas/2007/categories.cat.

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

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

    • אם האפליקציה מאפשרת למשתמשים להעלות סרטונים, צריך לאחזר גם קובץ קטגוריות מעודכן לפני העלאת הסרטון ולוודא שניתן עדיין להקצות את הקטגוריה המשויכת לסרטון שהועלה. מידע נוסף זמין במדריך העזר. (שימו לב שאם מנסים להקצות סרטון לקטגוריה שלא ניתן להקצות, ה-API יחזיר הודעת שגיאה שהערך של התג <code> הוא deprecated.)

  • יש להשתמש בתגי <link> בתגובת API כדי לזהות קישורי עימוד עבור הדף הקודם ו/או הדף הבא בפיד. מידע נוסף זמין בקטע עיון בתוצאות שבמדריך העזר.