streamalism.org

1. הבעיה

פיתוח ממשק API של REST היא בעיה קשה - אחת שעבורה אפשרויות רבות זמינות. מאמר זה דן בכמה מהאפשרויות הללו.

2. מה יש בחוזה?

לפני כל דבר אחר, עלינו לענות על שאלה אחת פשוטה: מהו החוזה בין ה- API לבין ה- לָקוּחַ?

2.1. URI הם חלק מהחוזה?

בואו נשקול קודם מבנה ה- URI של ה- REST API - האם זה חלק מהחוזה? האם הלקוחות צריכים לסמן סימניות, להקשיח ולהתבסס בדרך כלל על URI של ה- API?

אם זה המקרה, האינטראקציה של הלקוח עם שירות REST כבר לא תהיה מונעת על ידי השירות עצמו, אלא על ידי מה שרוי פילדינג מכנה. מחוץ להקה מֵידָע:

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

כל כך ברור URIs אינם חלק מהחוזה! הלקוח צריך להכיר רק URI יחיד - נקודת הכניסה ל- API. יש לגלות את כל שאר ה- URI בעת צריכת ה- API.

2.2. סוגי מדיה חלק מהחוזה?

מה לגבי המידע מסוג מדיה המשמש לייצוג משאבים - האם הם חלק מהחוזה בין הלקוח לשירות?

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

לכן, כאן שירות REST צריך להתמקד ביותר:

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

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

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

3. אפשרויות ברמה גבוהה

בואו נדון כעת בגישות ברמה הגבוהה לגרסת ה- API של REST:

• גרסת URI - גרסת שטח ה- URI באמצעות אינדיקטורי גרסה
• גרסאות סוג מדיה - גרסת ייצוג המשאב

כאשר אנו מציגים את הגרסה במרחב ה- URI, ייצוגי המשאבים נחשבים לבלתי ניתנים לשינוי. לכן כשצריך להכניס שינויים ב- API, צריך ליצור מרחב URI חדש.

לדוגמה, נניח ש- API מפרסם את המשאבים הבאים - משתמשים והרשאות:

// מארח / v1 / משתמשים // מארח / v1 / הרשאות

עכשיו, בואו ניקח בחשבון ששינוי שבור ב משתמשים API דורש הצגת גרסה שנייה:

// מארח / v2 / משתמשים // מארח / v2 / הרשאות

כאשר אנו מגדירים את סוג המדיה ומרחיבים את השפה, אנו עוברים משא ומתן על תוכן על בסיס כותרת זו. ממשק ה- API של REST ישתמש בסוגי מדיה MIME של ספקים מותאמים אישית במקום בסוגי מדיה כלליים כגון יישום / json. אנו הולכים לגרסא את סוגי המדיה הללו במקום את ה- URI.

לדוגמה:

===> GET / משתמשים / 3 HTTP / 1.1 קבל: application / vnd.myname.v1 + json <=== HTTP / 1.1 200 OK תוכן סוג: application / vnd.myname.v1 + json {"user": {"name": "John Smith"}}

אנו יכולים לעיין במאמר זה 'סוגי מדיה מותאמים אישית למנוחי API' לקבלת מידע נוסף ודוגמאות בנושא זה.

מה שחשוב להבין כאן זה הלקוח אינו מניח הנחות לגבי מבנה התגובה מעבר למה שמוגדר בסוג המדיה.

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

יוצא מן הכלל לכך הוא שימוש בדרך אחרת לזיהוי ייחודי של הסמנטיקה של התוכן - כמו סכימת XML.

4. יתרונות וחסרונות

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

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

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

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

מטמון HTTP הוא גם דאגה מרכזית בכל הנוגע לגירסאות.

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

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

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

בואו נסיים את החלק הזה בהגדרת מטרות מסוימות (היישר מהאבולוציה של API):

• לשמור על שינויים תואמים מחוץ לשמות
• הימנע מגרסאות עיקריות חדשות
• עושה שינויים תואמים לאחור
• לחשוב על תאימות קדימה

5. שינויים אפשריים בממשק ה- API

לאחר מכן, נבחן את סוגי השינויים ב- REST API - אלה מוצגים כאן:

• פורמט ייצוג משתנה
• שינויים במשאבים

5.1. הוספה לייצוג של משאב

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

עַכשָׁיו, הוספת מידע בייצוג של משאב לא תשבור לקוחות קיימים אם אלה מיושמים כהלכה.

להמשך הדוגמה הקודמת שלנו, הוספת ה- כמות בייצוג של מִשׁתַמֵשׁ לא יהיה שינוי שבור:

{"user": {"name": "John Smith", "amount": "300"}}

5.2. הסרה או שינוי של ייצוג קיים

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

כאן נכנס משא ומתן תוכן. לשינויים כאלה, אנו יכולים להוסיף סוג מדיה חדש של ספק MIME.

בואו נמשיך עם הדוגמה הקודמת. תגיד שאנחנו רוצים לשבור את שֵׁם של ה מִשׁתַמֵשׁ לְתוֹך שם פרטי ו שם משפחה:

===> GET / users / 3 HTTP / 1.1 Accept: application / vnd.myname.v2 + json <=== HTTP / 1.1 200 OK תוכן סוג: application / vnd.myname.v2 + json {"user": {"firstname": "John", "lastname": "Smith", "amount": "300"}}

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

5.3. שינויים סמנטיים גדולים

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

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

ממשק ה- API של REST צריך לעמוד במגבלת HATEOAS. על פי זה, לקוחות ה- URI צריכים להימצא על ידי לקוחות ולא לקודד אותם. אין לראות בשינוי URI כזה כשינוי שאינו תואם. ה- URI החדש יכול להחליף את הישן והלקוחות יוכלו לגלות מחדש את ה- URI ועדיין לתפקד.

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

6. מסקנה

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

המאמר מסתיים בכך שהוא פונה לפיתרון השני - גרסאות סוגי המדיה תוך בחינת השינויים האפשריים ב- API RESTful.

ניתן למצוא את היישום המלא של מדריך זה בפרויקט GitHub.

7. קריאה נוספת

בדרך כלל מקורות הקריאה הללו מקושרים לאורך המאמר, אך במקרה זה, ישנם פשוט יותר מדי טובים:

• • ממשקי API של REST חייבים להיות מונחים על ידי היפר-טקסט
  • אבולוציית API
  • קישור ל- API של HTTP
  • אסטרטגיות תאימות