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

בכל בקשה ל-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.

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

בקשות API

פונקציונליות שלא אמורה להשתנות

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

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

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

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

    • /feeds/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. אחרת, יכול להיות שהערך הזה יימחק.

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

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