‏הצגת רשומות עם תוויות REST. הצג את כל הרשומות
‏הצגת רשומות עם תוויות REST. הצג את כל הרשומות

2016-10-04

REST ו RESTful APIs - גרסת 2016

איי שם בשנת 2011 כתבתי פוסט על REST ו RESTful APIs. פוסט שנצפה דיי הרבה פעמים, וגם עורר שאלות ותגובות. לפני כשבוע שאל אותי עוד מישהו על אחת הדוגמאות שנתתי. דוגמה כיצד לא-לכתוב REST Endpoint.

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

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

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

רעיונות ה REST באמת גרמו לסחף אדיר בתעשיה, ושינו בתוך שנים ספורות את האופן בו אנו מגדירים APIs בין מערכות / תתי-מערכות.

מה כ"כ חזק ברעיונות ה REST שגרם לשינוי האדיר הזה?
מדוע פרוטוקולים "נבונים" יותר ו"מעודכנים" יותר, כמו GData, OData, או JSON API - לא זוכים לכזו תהודה?
מה סוד הקסם של REST?

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

כלומר: אפשר לומר שמרבית התעשייה עובדת עם "פסדו-REST", ורק חלקים קטנים יותר עובדים עם "REST תקני" או אפילו "REST תקני חלקית".
אם נשווה את מספר המשתמשים ב "REST תקני (חלקית)" - סדרי הגודל של המשתמשים דומים כנראה למספרי השמתמשים בפרוטוקולים חלופיים, קרי JSON API, OData, GData, או Thrift (שפותח במקור ע"י פייסבוק).

בעוד הפוסט המקורי מ-2011 נועד להוות "קריאת השכמה" ולהראות כיצד ליישם "REST תקני"... בפוסט הזה אני אנקוט גישה מעט שונה. בכל זאת, מתבגרים... :)




מה הרעיון ב REST?


הרעיון, ביישום המקובל שלו, הוא שבמקום ש"נמציא" פרוטוקול תקשורת חדש לווב, נשתמש בפרוטוקול של הווב - הרי הוא פרוטוקול ה HTTP. פרוטוקול אמין, מוכר, ומוכח ב Scales אדירים.

בגישה זו, יש מספר לא מבוטל של יתרונות:
  • ל HTTP יש המון ספריות, לכל שפת תכנות בערך, והרבה אנשים מכירים אותו לעומק. (אם אתם לא מכירים - זה זמן טוב לקורא את הפוסט בנושא!)
  • אם נפעל בהתאם ל HTTP, נוכל להינות בהשקעה קטנה מצידנו מ Caching שרכיבי הרשת השונים כבר מספקים (Proxies, gateways, CDNs, וכו').
  • רכיבי אבטחת רשת מקובלים (IDS או WAF) מכירים HTTP. הנה לנו פרוטוקול שכבר יש לו תמיכה בלא-מעט כלי אבטחה.
  • HTTP הוא פשוט ויעיל. מתחת למכסה המנוע הוא פשוט כמה headers שנשלחים לפני ההודעה על גבי חיבור ה TCP.
  • HTTP הוא stateless (ברובו הגדול), וה Scalability שלו היא מוכחת! (ה world wide web, דאא)
  • HTTP קל לניטור והבנה (יש הרבה כלים + הוא מבוסס clear text).


ע"פ ההגדרות הפורמאליות, REST אינו בהכרח קשור ל HTTP. הוא מבסס עקרונות (או Constraints) של ה API של המערכת, שדומים מאוד לאלו של רשת האינטרנט:
  • תקשורת שרת-לקוח
  • ה API הוא Stateless
  • ניתן לבצע Cache לבקשות
  • ממשק אחיד, לכלל המערכת:
    • מבוסס מיפוי של משאבים (כלל מנחה: שמם מורכב משמות-עצם)
    • על כל המשאבים ניתן לבצע סט מוגדר של פעולות: קריאה, כתיבה, עדכון, וכו'. (דומה מאוד ל HTTP GET, HTTP POST, וכו').
    • ה API מתאר את עצמו - ולקוח ה API משתמש בתיאור זה בצורה "גנרית" על מנת להשתמש ב API.

כיצד הסתירה הזו מתיישבת? נסביר בהמשך.







היסטוריה: כיצד נולד ה REST?


רעיונות ה REST הופיעו בפעם הראשונה בעבודת הדוקטורט של Roy T. Fielding, חבר בצוות שהגדיר את פרוטוקול ה HTTP וכן co-author של ה Apache Web Server.

עבודת הדוקטורט של פידלינג עסקה באפיון של רעיון שנקרא "סגנונות ארכיטקטוניים", מן דפוסים מרכזיים וחוזרים בארכיטקטורות של תוכנות שונות. בפרק מספר 5 בעבודה הוא תיאר סגנון ארכיטקטוני בשם (Representational State Transfer (REST - אימוץ העקרונות מאחורי ה world wide web, על מנת לתקשר בין שרתים.

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

כמה שנים לאחר מכן, ב 2003 עד 2005 בערך - העולם נכנס לסערה של Service Oriented Architecture (בקיצור: SOA) והרעיון של Web Services (רשימת תקנים בשם *-WS).
אפשר להשוות את ההשפעה של SOA לאופנה הנוכחית של Microservices. לי, כמפתח צעיר, הרעיונות נשמעו מלהיבים וגדולים - ובחברה שעבדתי בה באותה התקופה החליטו "לא לפגר מאחור - ולאמץ SOA עד הסוף". כמובן שלי ולחברי לא היה מושג בדיוק כיצד להוציא מ SOA את המיטב - ופשוט מימשנו SOA ו Web Services.

Web-Services היו הפשטה גבוהה ועשירה/מסובכת מעל הפרימיטיביים של הווב. היה שם XMLs גדולים ומורכבים, שנעטפו בתוך XML נוסף (ה envelope) שהיה חלק מפרוטוקול התקשורת - SOAP, ותוארו ע"י פורמט שנקרא WSDL והופץ על גבי פרוטוקול בשם UDDI ואז היה ניתן להשתמש בכלי בשם DISCO על מנת למצוא אותם. וזה היה רק הבסיס.

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

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

ב 2004 ה W3C (ארגון התקינה של האינטרנט) הוציא מסמך שדן בארכיטקטורות אינטרנט. לקראת סוף המסמך, הופיעה פסקה קצרה המרחיבה את ההגדרה של Web Services: היא גם ציינה את REST כבסיס התיאורטי לפעולת ה Web Services, וגם ציין שהם יכולים להיות בלתי-תלויים בפרוטוקולים כמו WSDL או SOAP.

יריית הפתיחה נורתה, ושני מחנות החלו להיווצר:
  • אלו התומכים ב Web Services ע"פ סט תקני ה *-WS.
  • אלו התמוכים ב RESTful Web Services, כלומר: עלינו רק לתאום לכללי ה REST - וזהו Web Service בר-תוקף, בהכשרת ה W3C!
על עצם הצורך בהגדרה של Web Services, או של SOA - אף אחד לא ערער. זה היה באזז חזק שלא ניתן להתכחש לו.
היום כמעט כבר אין ממש זכר ל *-WS, ומעט מאוד מ SOA. הקונצנזוס הגדול התעשייה הוא סביב REST - כאשר עדיין יש הרבה חוסר הבנה מסביב לעקרונות הללו.


קצת עזרה מידידנו ריצארדסון


את חוסר ההבנה ב REST, ניסה קצת להבהיר / לסדר בחור בשם לאונרד ריצרדסון.

ריצרדסון הוא המחבר של שני ספרים מוכרים (הוצאת O'Reilly):
  • RESTful Web Services - 2007
  • RESTful Web APIs - 2013
בהרצאה בכנס QCON-2008, ריצרדסון הציג מודל בגרות של אימוץ רעיונות ה REST:

מקור: http://www.slideshare.net/josdirksen/rest-from-get-to-hateoas


רמה 0 - הביצה של POX (קיצור של Plain Old XML. פורמט ה XML היה בזמנו יותר פופולרי מ JSON)

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

זה כמובן לא מפריע לקרוא לו REST - ויש אנשים שבאמת מתייחסים לכל פורמט סטנדרטי (נניח JSON) שעובר ל HTTP - כ REST. לא נבוא איתם בחשבון :-)



רמה 1 - מיפוי משאבים

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

בעוד שיכולנו לתאר API של מערכת לניהול כנסים כ:

  • POST /create_session
  • POST /set-session-title
מיפוי של משאבים יתייחס לקריאות הללו בצורה בה מתייחסים למשאבים:
  • POST /sessions/create
  • POST /sessions/<session_id>/title

מכיוון שה title שייך ל session, אנו מרכיבים את ה URI בצורה היררכית - כך ש session קודם (ולכן "מכיל") את ה title. כלומר: כל "/" מתאר בהכרח רמה היררכית של מבנה המשאבים.


מיפוי המשאבים מציב כל מיני דילמות, שאין להן תשובה חד משמעית:
  • כאשר אין קשר היררכיי ברור בין ה resources  - מה הסדר הנכון?
    • למשל: הזמנת-נסיעה ונהג - מי מכיל את מי? (בהנחה שכל אחד מהם הוא אובייקט שחי בפני עצמו. הזמנת-נסיעה נוצרת בלי קשר להשמה לנהג).
  • רזולוציה: האם למפות כל תכונה של אובייקט (למשל: title) לresource שיש לו URI משלו, או פשוט להסתפק ב sessions/update/ עבור כל התכונות יחדיו (בהתאם לפרמטרים שנשלחים בבקשה)?
  • כיצד לתאר גרסאות שונות של ה API? כחלק מה URI או כפרמטר?
  • ועוד...


רמה 2 - שימוש ב HTTP Verbs (ו Status Codes)

שימוש ב Method (נקראים גם Verbs) של פרוטוקול HTTP בכדי לתאר את הסמנטיקה של הפעולה:
  • GET - על מנת לבקש את ה state של המשאב אליו מפנה ה URI.
  • POST - על מנת לשלוח content ("נתונים"/"הודעה") למשאב לצורך עיבוד, עיבוד שייתכן וישנה את ה state של המשאב. לעתים הודעה זו תיצור תת-משאב (ואז נהוג להחזיר Status Code של 201 - "נוצר").
  • PUT - על מנת להחליף (rebind - "רישום מחדש") של התוכן של המשאב.
  • PATCH - על מנת לבצע עדכון חלקי של ה state של המשאב.
  • DELETE - על מנת למחוק את המשאב.
ניתן כמובן להשתמש גם במתודות האחרות של פרוטוקול ה HTTP,קרי HEAD, OPTIONS, TRACE - אולם הגדרת ההתנהגות שלהן עבור REST API היא פחות ברורה ויותר פתוחה לפרשנות.

כלל חשוב נוסף הוא שאין חובה לתמוך בכל 4 הפעולות הבסיסיות על כל משאב. ייתכן משאב שעליו ניתן לבצע רק GET ומשאב אחר שעליו אפשר לבצע רק POST. מצד שני הגדרת ה URI מחייבת שכל צומת מתאר משאב שניתן לגשת אליו. לדוגמה, אם הגדרתי משאב כ:

http://example.com/orders/2009/10/776654

אזי גם ה URIs הבאים צריכים להיות ברי-קיום:

http://example.com/orders/2009/10
http://example.com/orders/2009
http://example.com/orders
http://example.com

יתרון גדול בשימוש ב HTTP Verbs היא "קבלת Caching" בעלות מזערית. רכיבי רשת רבים: שרתי ווב, CDNs, רכיבי פרוקסי ו Gateway - מודעים ומכבדים את ה Verbs הללו. אם אנו עושים הרבה GET (ובעיקר: מוסיפים גם headers נכונים) - התשובה תהיה cached ב"רשת". כאשר נבצע POST לאותו משאב - ה caches יתנקו.

יתרון נוסף הוא שרכיבי אבטחת רשת IDS, WAF, ועוד - מודעים לבקשות הללו ול HTTP error codes - יודעים על פיהן להסיק ולזהות התנהגות חריגה / מסוכנת ברשת שלנו.

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

ההתנהגויות המוגדרות של HTTP verbs השונים. מקור: Lynda.com

עוד מידע על התנהגות ה HTTP הצפויה מה verbs השונים, ועל שימוש ב Status Codes - ניתן למצוא בפוסט על פרוטוקול ה HTTP.

כפי שתיארו את זה ריצרדסון ורובי בספר, הכוונה היא שפרוטוקול ה HTTP (או פרוטוקול אחר, רעיונות ה REST לא מתייחסים בהכרח ל HTTP) ישמש באותה המידה משתמשים אנושיים, ומכונות (צרכני API) באותה המידה ו(כמעט) באותו האופן:

"...Reunite the programmable web with the human Web... a World Wide Web that runs on one set of servers, uses one set of protocols, and obeys one set of design principles"
 -- Richardson & Ruby, RESTful web services, 2007.




רמה 3 - Hypermedia Controls

שמות נרדפים: Hypermedia transformations או Hypermedia As the Engine Of Application State (בקיצור: HATEOAS)

רעיון זה טוען שעל פעולה ב REST למשאב צריכה לתאר את פעולות ההמשך האפשריות כ links לפעולות הללו.
כשאנו גולשים באינטרנט, אנו הולכים למשאב מרכזי, למשל: https://www.bankhapoalim.co.il - ומשם אנו משתמשים בקישורים על מנת לבצע את שאר הפעולות: כניסה לחשבון, ביצוע העברה בנקאית, שליחת טופס לנציג הבנקאי האישי שביצענו טעות בהעברה הבנקאית (!!) - וכו'...

באופן דומה, הרעיון ב REST הוא שהתוכנה בצד השני (ה Client) לא "תדע" אלו פעולות זמינות, אלא תלמד אותן מהתשובה. למשל:



התשובה שלנו לכל קריאה, מכילה גם links שהם תיאור של הפעולות האפשריות. self למשל היא הפעולה הנוכחית, כאשר אני גם יכול לבצע product.search - ויש בידי את ה URI המתאים לביצוע התחזוקה.

עוד השלכה חשובה של ה HATEOAS היא שכל פנייה לשרת צריכה לפתוח בקריאת GET (או OPTIONS - לדקדקנים), ורק אחריה קריאת POST או PUT וכו'. יש מערכות שמסתמכות על ההנחה הזו.


משתמש אנושי יכול באמת להבין מה המשמעות של "product.search", אבל מה מכונה מבינה מזה? ישנן שתי אופציות:
  • המכונה מכירה את כל ערכי ה rel האפשריים - ולכן יודעת לפעול על פיהם.
  • המכונה לא מבינה.
הפער הזה נקרא ה Semantic Gap, עניין שאנשי ה Semantic Web (מספרם קצת הצטמצם בשנים האחרונות, לא?) - מנסים לפתור.

ישנם פרוטוקולים כמו XMDP או ALPS לתיאור סמנטיקה של פעולות API. מן שפות של meta descriptions.

מי שממשיך ומתקדם מעל רמה 3 - ראוי להיכנס להיכל התהילה של REST, כמי שיישם את מודל ה REST בצורתו הטהורה ביותר!



ספר על REST? - יש עשרות רבות...


מודל ה REST בפועל


האם זה הגיוני ליישם את שלב 3 במודל של ריצ'רדסון, Hypermedia Controls?
אם אתם מפתחים מערכת ווב טיפוסית - ברור שלא!

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

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

דווקא ריצרדסון שהגדיר את מודל ה maturity ציין בראיונות מאוחרים יותר שהוא ניסה לספק שלבים כיצד לאמץ REST בהדרגה, ומבחינתו עצירה ברמות 1 או 2 - הן גם טובות.

לדעתי האישית, אין טעם ברמה 1 ללא רמה 2: מיפוי משאבים ללא שימוש ב Verbs הוא אנמי וחסר. הייתי ממליץ על רמה 2 או 0, עם הסתייגויות.

ההסתייגויות הן שכללים רבים של "REST טהור" עשויים להיות פשוט לא יעילים ליישום במערכת שלכם. הם יכולים לגזול זמן מיותר - ולספק מעט תועלת.

הנה כמה כללים שאנחנו נוהגים להתעלם מהם במערכת הקיימת שלנו (בידיעה):
  • הפער הגדול ביותר: אנו משתמשים בפעולות POST גם לצורך קריאות שלא משנות את ה state של האובייקט. פשוט כמו GET שמכיל payload גדול יותר, אפילו אם לא מתבצע processing מורכב מאחורי הקלעים.
    • זה אומר ששברנו כמה כללים של ה HTTP: חלק מקריאות ה POST הן עכשיו cacheable ו idempotent.
    • מצד שני: שרשור של פרמטרים ה URL זה פחות קל, ופחות קריא. הכי מעצבן היה לגלות שוב ושוב חסימות לאורך ה URL ברכיבי הרשת השונים: פעם ב WAF, פעם nginx - ופעם ב Load Balancer. אמנם אין הגבלה בתקן ה HTTP עצמו, אבל כנראה שבעקבות הדפדפנים שנהגו להגביל את אורך ה URL - נראה שגם רכיבי הרשת אמצו, כברירת מחדל, את המסורת...
  • לא כל חלק של URI הוא בר-תוקף. ייתכן וישנו URI בשם {companies/{id}/roles/{role_id/ מבלי שיש ל companies/{id}/roles/ כל תוקף. למה לנו לפתח API שאף אחד לא הולך לקרוא לו?
  • אנחנו משלבים שמות של פעולות, ולא רק משאבים ב URI. אנחנו משלבים אותן בסוף, כמעט-תמיד. למשל:
    areas/by_point ו areas/by_rectangle. 
  • אם פעולה יצרה משאב חדש, אנו לא מחזירים header של location עם ה URI למשאב שנוצר. הרבה יותר פשוט להחזיר id של האובייקט החדש בתוך ה JSON של התשובה.
  • ויש כנראה עוד...

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

כמו שאני נוהג להטיף, גם כאן אני מציע: השתמשו בכל כלי בצורה שהכי מועילה לכם, ולא ע"פ כלל שרשום איפשהו.

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

אנו כן מקפידים ב REST לשמור על הכללים הבסיסיים:
  • למדל בצורה סמנטית (קרי - ברורה מפתח) ובחשיבה על resources במבנה היררכי את URIs שאנו משתמשים בהם.
  • להקפיד על שימוש ב Verbs של HTTP ועל Status Codes בסמנטיקה שהוגדרה להם. אנו לא משתמשים ב Verbs ו Status Codes שאינם חלק מתקן ה HTTP (על אף שתקן ה HTTP עצמו - מותיר זאת).
  • להיות "Good Citizens", ולהתאים את התנהגות ה APIs שלנו לכללי ה HTTP במידת האפשר.

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




שיהיה בהצלחה!


---

קישורים רלוונטיים

הבלוג של מרטין פאוולר, על Richardson Maturity Model ו REST:
http://martinfowler.com/articles/richardsonMaturityModel.html

מצגת נחמדה שמתארת כמה מהבעיות שעלולות לצוץ ביישום REST (הרשאות, גרסאות שונות של API, טיפול בשגיאות, וכו'):
http://www.slideshare.net/MasoudKalali/masoudkalalirest-new-format


2015-03-06

ריילס: routing

נדבך חשוב בריילס הוא ה routing, המיפוי איזה Action (=מתודה) של איזה Controller תופעל ל URL נתון.
הרכיב שעושה את ה routing נקרא ActionDispatcher.

ה routing מתבצע באפליקציה בקובץ בשם config/routes.rb בעזרת סט פקודות מיוחדות (בעצם: DSL) שמגדיר את ה routes. סט הפקודות הזמין הוא עשיר ומגוון למדי, ולרוע המזל - אינו מתועד בצורה נוחה ללמידה. לא כ"כ באנגלית - ובוודאי שלא בעברית.


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

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

כפי שנראה ה routing של ריילס מבוסס עמוקות על עקרונות ה REST - ניתן לקרוא בקצרה על עקרונות ה REST בפוסט הזה על REST או בפוסט על HTTP.
לפני ריילס 3, הגדרת ה routes הייתה מסורבלת למדי. אני מתעלם מתחביר זה לחלוטין, ומתמקד במה שזמין בריילס 3 ו 4 (או ליתר דיוק: מתייחס למצב בריילס 4.2).





האנטומיה של route


הנה דוגמה ל route טיפוסי:

  1. HTTP verb / method
  2. pattern של URL יחסי, המכיל בתוכו:
  3. segment key (אחד או יותר) - המוגדר כ "symbol" ב path.
    segment key ממפה ארגומנטים שמועברים ב URL (או כ Query String[א]).
  4. יעד המיפוי, בפורמט: "controller#action". שם ה controller מופיע ללא המילה Controller ובאותיות קטנות (בכדי לקצר בכתיבה). Action הוא שם המתודה ב controller שמטפלת באירוע.
  5. רשימת אופציות ל routing. במקרה שלנו יש אופציה אחת בשם "as:" עם ערך של "purchase" (הסבר על אופציה זו - בהמשך).

routes יכולים להיות מוגדרים בצורות שונות, ואף מורכבות יותר - על מבנים אלו נדבר בהמשך.

בריילס 3, היה מקובל להגדיר routes פשוטים בעזרת פקודת match, למשל:

match 'products/:id' => 'products#show', via: :get

via הוא פרמטר שמגביל את ההתאמה ל HTTP verb/method מסוים (אפשר גם לשלוח רשימה - במערך), והוא היה אופציונלי עד גרסה 4 של ריילס. בגרסה 4 זו הפכה לחובה (RuntimeError ייזרק אם לא הוגדרה http method, אפשר להשתמש גם ב any:, אם כי לא מומלץ).

הדרישה להגבלת ה http method נולדה משיקולי אבטחה ואמינות של המוצר. מומלץ תמיד להגדיר HTTP verb יחיד ל route, ולצורך כך נוספו הקיצורים get, post, put וכו' - שהם כתיבה מקוצרת ל <match... via:<method.
מעתה והלאה נעבוד רק איתם, אך כדאי לזכור שבמקור הם קיצור תחבירי ל match ושאת הפרטים על האופציות השונות הזמינות ל route - יש עדיין לחפש בתיעוד של match.

הצורות הבאות, הן צורות מקבילות לחלוטין ל route שהגדרנו למעלה, שקצת פחות מקובלות היום (ישנות, ויותר ארוכות):

match 'products/:id', to: 'products#show', via: :get
match 'products/:id', controller: 'products', action: 'show', via: :get

אני מזכיר אותן, כי ייתכן שתתקלו בפרמטרים של to: ו controller: ב routes - ושתבינו את משמעותם / מקורם.

בקיצור, היום נכתוב את ה route הזה באופן הבא:

get 'products/:id' => 'products#show'

משמעות ההגדרה הזו היא:
אם יש קריאת GET עם URL המתאים לדפוס "<products/<x", קרא ל controller בשם ProductsController (שנמצא בתיקיה app/controllers/) ולמתודה בשם show, ושלח כארגומנט את המחרוזת x כערך של הפרמטר "id:".
את הערך ניתן לקרוא בתוך ה controller בעזרת המתודה params, למשל:

params[:id] # string "x"


כיצד זה עובד?


הנה דוגמת קוד מינימלית לשימוש ב routing, controller, ו view:



  • בקובץ ה routes.rb, הגדרנו route בסיסי - שאתם אמורים כבר להבין
  • ה Controller (הקטן ביותר האפשרי, בערך) מכיל מתודה (= action) בשם show שאליה ה route שהגדרנו יפנה. היא מחפשת במודל את המוצר ושומרת אותו כ product@.
  • כשה Controller יוצר את ה View, ריילס באופן "פלאי" (הסבר) מעתיק את ה instance variables, על ערכיהם, מה Controller (כדוגמת product@) ל View. משם, ניתן לגשת לשדות השונים בתוך ה product.
  • שימו לב לפקודה בשם link_to אותה תראו הרבה ב views של ריילס. היא מייצרת עבורנו link עם הכותרת שהגדרנו ("Show Details") לפעולה מסוימת של ה Controller. כיצד זה עובד? - נסביר בהמשך.


אופציות מתקדמות יותר להגדרת routes


Segment Keys אופציונליים
ממש כמו optional parameters בפונקציה, יש גם Segment Keys אופציונליים ב route. למשל:

get 'products/:id(/:facet)' => 'products#show'

יתאים ל 2 צורות של url, למשל:

http://site.com/products/441
http://site.com/products/441/specifications
במקרה הראשון יהיה ערך רק לפרמטר id: (הערך = '441'), ו facet: יהיה nil.
במקרה השני facet: יהיה שווה 'specifications'

שימו לב לצורה הנפוצה הבאה:

get 'products/:id(.:format)' => 'products#show'

המשמעות שלה היא matching ל url מהנוסח הבא:

http://site.com/products/441.json

כאשר הפרמטר format: מקבל את הערך 'json'.
הנקודה שליד שם הפרמטר מתארת את חלק מה Path.

ספציפית לגבי format:, זהו פרמטר עם התנהגות מיוחדת: פקודת respond_to שבשימוש בתוך ה controllers בודקת את הערך שלו, ולפיו מחליטה כיצד לפעול (האם להחזיר HTML או json - בד"כ).


Redirect
ניתן להגדיר route שיבצע redirect ל URL אחר ברשת. למשל:

get 'products/:id', to: redirect('v2/products/:id')

המילה to: מגיעה מתוך התחביר הישן של match שהזכרנו למעלה.
הערך של to: הוא Rack Endpoint שיכול להיות קוד inline (בשימוש בפונקציות lambda או proc) או שם של אפליקציית Rack אחרת (שיושבת בתיקייה app/metal/), או סתם URL אחר (כמו במקרה שלנו).


Constraints
אופציה זו מאפשרת לנו להציג תנאים נוספים (בדמות RegEx) על ה matching של ה route. למשל:

get 'products/:id' => 'products#show', constraints: {:id => /\d+/}

תתאים רק כאשר ה id: הוא מספר (ולא כולל אותיות, למשל).
בגלל ש constraint הוא כ"כ נפוץ על שדה שנקרא id:, נוצר לכך קיצור מיוחד בריילס. את הדוגמה הנ"ל ניתן לכתוב גם כך:

get 'products/:id' => 'products#show', id: /\d+/

ניתן להשתמש ב constraints על מנת לעשות בדיקת קלט למשתמש - אך זה לא מומלץ!
הכלי הוא יחסית מוגבל, וקובץ ה routing הוא לא בהכרח המקום הנכון לעשות זאת.
הכלל המנחה הוא להוסיף constraint על route, אם יש לכם route אחר שיתאים במקום. למשל:

get 'products/:id' => 'v2/products#show', id: /\d+/
get 'products/:id' => 'v1/products#show'


כלומר: בעבר קיבלתי מוצרים עם id: מכל סוג, ומתישהו (v2) הגבלתי אותם רק למספרים.
אם מופיע בקשה עם id: שאינו מספר - שלח אותה לטיפול ב controller הישן.

ל constraints יש גמישות נוספת מעבר לבדיקת ערכי segment keys, ניתן לקרוא עוד בנושא בפוסט הבא.


Wildcard Segment
אם מבנה ה URL מכיל מידע, ויכול להופיע בווריאציות שונות, ניתן להשתמש ב wildcard segment. כלומר, ה route:
get 'products/*other' => 'products#show'
יתאים ל URL כמו:

http://site.com/products/my/id/366/type/special/

וישלח ל controller משתנה בשם other: שערכו הוא 'my/id/366/type/special'.

ניתן להרכיב Wildcard Segments, עם Segment Keys רגילים. אם אתם זקוקים לעוד מידע בנושא חפשו את המונחים Wildcard Segment או Route Globbing.



רשימת יכולות שכיסינו כאן כנראה מכסה את רוב השימושים הנפוצים.
ניתן לקרוא בתיעוד הרשמי, Rails Routing from the Outside In, על אפשרויות נוספות.






Named Routes


מנגנון ה Named Routes בא לפשט (אפילו יותר) את העבודה עם routes.

כאשר נותנים ל route את השם "abc", ייווצרו שתי מתודות הזמינות לשימוש ב Controllers וה Views: אחת בשם abc_url, והשנייה abc_path.
  • המתודה abc_url היא תייצר url מלא שיתמפה ל route שהגדרנו.
  • המתודה abc_path תייצר את את חלק ה path של ה url, בלי protocol/host/port.

מנגנון ה Routing של ריילס בעצם משמש לשני כיוונים: גם לפענוח URL והתאמתו ל route (ומשם ל controller#action), וגם לצורך generation של URL (או path) שיוביל ל route שהוגדר.

הנה דוגמה:

get 'products/:id' => 'products#show', as: :show_product


תיצור את 2 המתודות show_product_url ו show_product_path על אובייקט ה app שזמין ל controllers וה views.

עכשיו אפשר ליצור קיצור ל path הזה מתוך אחד ה views בעזרת פקודת link_to. הפקודה, בגרסתה הארוכה, מקבלת hash כפרמטר:

link_to "הצג מוצר",
  controller: "products",
  action: "show",
  id: 12

אך בעקבות השימוש ב as:, יש לנו דרך מקוצרת להפעיל אותה:

link_to "הצג מוצר", show_product_url(id: 12)

יש לנו את מתודת העזר show_product_url שחוסכת מאתנו להגדיר Controller ו Action בנפרד. זה גם יותר קצר, וגם קוד שקל יותר לתחזוקה. (למשל: במידה ומשנים את שם ה Controller)


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

אם הערך שאתם רוצים לספק כפרמטר לפונקציית ה abc_url הוא id: - אז אתם יכולים לשלוח את הערך וזהו, בלי hash. למשל:

link_to "הצג מוצר", show_product_url(12)

בד"כ זה לא יהיה ערך עצמו אלא משתנה. למשל product.id, כאשר product הוא המודל שהכנתם ב controller. במקרה כזה ניתן לקצר אפילו יותר ולשלוח פשוט אובייקט:

link_to "הצג מוצר", show_product_url(product)

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


עבור debugging, ניתן להריץ את הפונקציות xxx_url/xxx_path אובייקט ה app (מבלי להריץ את ה view). למשל:

app.show_product_path(12) # '/products/12'



שאלה של סגנון
מה ההבדל בין הפונקציה show_product_url לפונקציה show_product_path? מתי יש להשתמש בכל אחת מהן?

זה בעיקר עניין של סגנון:
  • show_product_url מייצרת Fully Qualified URL (כלומר: URL מלא ועצמאי), כפי שנדרש בתקן ה HTTP בפעולות redirect.
  • show_product_path, מייצרת URL רלטיבי שהדפדפן ידע להפוך אותו למלא בעת הצורך. ה URL קצר יותר ולכן נוח יותר לעבוד עם קבצי ה html שנוצרו. 
אז מה אתם מעדיפים? להיות דקדקנים (url, לעבוד ע"פ התקן) או לא לכתוב קצר (path, הדרך של ריילס)? עניין שלכם.
אני בד"כ מעדיף להיות דקדקן, אבל גם לפני ריילס עבדתי עם URLs יחסיים - וכך נראה לי שאמשיך.

בכל מקרה, כדאי להכיר של helper functions יש עלות של ביצועים. בזמן ריצה הן מחפשות בטבלת ה routing מה שלוקח זמן. קריאה ל link_to עם controller ו action - היא אפילו יותר יקרה.






Scoping


scope הוא מנגנון שעוזר לארגן את ה routes בקובץ ה routes.rb, ולחסוך כמה שורות קוד על הדרך. יש לו הרבה מאוד וריאציות של קיצור - אציג כמה מהעיקריות שבהן.
  # original
  get 'drivers/new' => 'drivers#new', as: :driver_new
  get 'drivers/edit/:id' => 'drivers#edit', as: :driver_edit
  post 'drivers/reassign/:id' => 'drivers#reassign', as: :driver_reassign

  # scope - DRY a bit with controller (1)
  # alternatives: "controller :drivers do ...", "scope :driver do"
  scope controller: :drivers do
    get 'drivers/new' => :new, as: :driver_new
    get 'drivers/edit/:id' => :edit, as: :driver_edit
    post 'drivers/reassign/:id' => :reassign, as: :driver_reassign
  end

  # scope - DRY a bit more with path (2)
  scope path: '/drivers', controller: :drivers do
    get 'new' => :new, as: :driver_new
    get 'edit/:id' => :edit, as: :driver_edit
    post 'reassign/:id' => :reassign, as: :driver_reassign
  end

  # scope - DRY a bit further with default params (3)
  scope '/drivers', controller: :drivers, as: 'driver' do
    get 'new' => :new, as: 'new'
    get 'edit/:id' => :edit, as: 'edit'
    post 'reassign/:id' => :reassign, as: 'reassign'
  end
במקור היו לנו 3 routes שהיינו צריכים להקליד לכל אחד כמה וכמה תווים...
  1. הגדרנו, בעזרת הפקודה scope, לכולם controller אחיד, וכך קיצרנו את הגדרות ה controller#action לשם ה action בלבד. יש עוד 2 דרכים להגיע לתחביר המקוצר הזה (בהערה, השני יכול לבלבל).
  2. הגדרנו path, שמקצר את חלק ה relative URL ב route.
  3. הגדרנו as, שמהווה prefix ל as: של ה routes הספציפיים, והצבנו את ה path כארגומנט הראשון לפונקציה scope, מה שמאפשר לנו לוותר את המפתח path:.
  4. אפשר לוותר על כל המופעים של אותיות a ו e - וריילס ישלים אותם בעצמו על סמך מילון מוכן מראש. סתאאםם.
אם אתם רואים את התוצאה הסופית וחושבים שניתן היה לקצר אותה יותר - אתם צודקים.

עוד פרמטר פופולרי של scope הוא module: :abc שמניח ש:
  1. ה Controller שייך ל Module (שפת רובי) בשם Abc. כלומר Abc::SomeController.
  2. => ה Controller נמצא בתת תיקיה בשם abc/

ישנה פונקציית קיצור בשם namespace שפועלת כך:
  namespace :drivers do
    # routes
  end

  # syntactic sugar of / equivalent to writing:
  scope path: '/drivers', module: :drivers, as: 'driver' do
    # routes
  end



הקיצור האולטימטיבי ליצירת routes


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

כחלק מההתאמה של ריילס למודל ה REST, הוגדר ל Controller סט ה Actions הגנרי הבא:
  • index - הצגת רשימה של אובייקטים
  • create - יצירת אובייקט חדש (מתוך פעולת POST)
  • new - החזרת template ליצירת אובייקט חדש (ללא יצירת האובייקט בפועל). בד"כ מדובר בהחזרת טופס וובי, "יצירת אובייקט חדש", למשתמש.
  • show - הצגת הפרטים של אובייקט מסוים
  • update - עדכון אובייקט מסוים
  • edit - החזרת template לעדכון אובייקט חדש. בד"כ מדובר בהחזרת טופס וובי "עדכון" אובייקט שבעקבותיו תגיע פעולת update.
  • destroy - מחיקת אובייקט מסוים

הפקודה הבאה, תמפה סדרה של routes עבור שבע הפעולות:
resources :products

# syntactic sugar of / equivalent to writing:
get 'products(.:format)' => 'products#index', as: :products # e.g. products_url()
post 'products(.:format)' => 'products#create',
get 'products/new(.:format)' => 'products#new', as: :new_product # e.g. new_product_url(12)
get 'products/:id/edit(.:format)' => 'products#edit', as: :edit_product # e.g. edit_product_url(12)
get 'products/:id(.:format)' => 'products#show', as: :product # e.g. product_url(12)
patch 'products/:id(.:format)' => 'products#update',
delete 'products/:id(.:format)' => 'products#delete'

למיטב הבנתי, ה named routes נוצר רק לפעולות ה get, מכיוון שרק לפעולות אלו ניתן לעשות re-direct בפדפדפן.

שימו לב שאם יש לנו route כמו הבא, שמופיע אחרי שורת ה resources:

get 'products/poll' => 'products#poll'

לעולם לא יגיעו אליו. ריילס תתאים אותו ל products/:id שנוצר בעקבות פקודת ה resources. הדרך היחידה שיוכלו להגיע אליו הוא אם נציב את ה route הזה לפני פקודת ה resources. ההתאמה ל routes נעשית בסדר שבו הם מופיעים בקובץ.

אם אתם רוצים להשתמש בפקודת ה resources עבור רק כמה מהפעולות, אין בעיה. פשוט כתבו:

resources :products, only: [:index, :show, :edit]

או השתמשו בפקודה ההופכית: except:.







קינון routes


קינון של routes מתבצע לרוב בין שני אובייקטים (REST resources) שיש בניהם קשר של שייכות. דוגמה שחוקה: כתבה, והערות לכתבה. מהות הקשר שמומלץ לנהל עבורו routes מקוננים הוא קשר "חזק" של הרכבה (composition), כאשר לאובייקט התלוי (למשל הערה) אין משמעות ללא אובייקט האב. למשל: כאשר מוחקים כתבה, טבעי שמוחקים את ההערות שלה. לא טבעי יהיה, בד"כ, למחוק את אובייקט המחבר - וזו אינדיקציה טובה שלא כדאי לקנן את המחבר תחת כתבה, אפילו שיש ביניהם קשר.

הנה דוגמה לקינון:
resources :articles do
  resources :comments
end

# generates 7 routes for articles + routes such as:
  get 'articles/:article_id/comments' => 'comments#show'
  get 'articles/:article_id/comments/new' => 'comments#new'
  put 'articles/:article_id/comments/:id' => 'comments#update'
... את הרשימה המלאה של ה routes הנוספים שנוצרים ניתן להסיק או לבדוק את הרשימה בתיעוד הרשמי.
כמובן שה routes של article יפנו ל ArticlesController וה routes המקוננים יפנו ל CommentsController. הקינון, חוץ מזה שהוא נוח מבחינת מידול ה REST, מאפשר ל CommentsController לקבל גם את ה article_id:.

עוד כלל הוא לעולם לא לעשות nesting עמוק (כלומר: 2

הנה עוד 2 כלים נפוצים, member ו collection, המאפשרים להוסיף פעולות חדשות:
resources :articles do
  member do
    get :preview
  end
  collection do
    get :search
  end
end

member מוסיף תחת ה resource עוד פעולה, אולי כזו שלא מוגדרת ב default, למשל preview. הפעולה היא כזו שמוגדרת על אובייקט יחיד - ולכן יש צורך במזהה. למשל, במקרה הנ"ל ייווצר ה route הבא:

/articles/:id/:preview

collection הוא דומה מאוד, אבל מגדיר פעולה על סט ה resources, כזו שלא צריכה מזהה. בדוגמה הנ"ל:

/articles/search



בדיקת ה routes בפועל

כדי לבדוק שה routes נכונים, יש בריילס 2 כלים שימושיים:

  • מ command line, בעזרת הפקודה rake routes. ניתן לבדוק Controller ממוקד ע"י שימוש בפרמטר, למשל: rake routes CONTROLLER=articles.
  • כאשר השרת רץ (rails s), ניתן לראות את רשימת ה routes תחת ה path הבא: rails/info/routes/




סיכום


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

כפי שאתם רואים אני עוד שקוע ריילס - ויש עוד כברת דרך....


שיהיה בהצלחה!




-----

לינקים רלוונטיים

פיצול ה routes לקבצים שונים


-----

[א] ה route:

get 'some_path/:a/:b/:c' => ...

יקבל ערכים זהים עבור 2 ה urls הבאים:

/some_path/xx/yy/zz
/some_path/xx?a=yy&b=zz


2012-02-11

הו-נתונים! - (AtomPub) חלק 2

זהו פוסט המשך לפוסט ההקדמה על ODATA.

במידה ואתם תוהים כיצד אמור להראות מימוש REST - אז AtomPub הוא דוגמא טובה. הוא תקן ותיק (יחסית, אתם יודעים) שהוכיח את עצמו ורץ בהרבה מערכות, גם של סטארט-אפים קטנים וגם מערכות Enterprise גדולות. יתרה מזו, הוא זכה לכמה הרחבות שהחשובות בהן הן GDATA ו ODATA. ללמוד ולהבין את AtomPub הוא תרגיל טוב על מנת להבין את ODATA - ולשם אנחנו חותרים. GDATA דומה בהרבה ל"מקור", אם כי כמה דברים מעניינים לדבר עליהם.

AtomPub - תקן פיצוץ

מבוא לפאב האטום (AtomPub)
בתחילה היה פורמט RSS - פורמט מבוסס XML לתיאור בלוגים. RSS זכה (וזוכה) לפופולאריות רבה בקרב אתרי חדשות ובלוגים.
אולם, ל RSS יש כמה בעיות: התקן לא מפורט עד הסוף ומשאיר כמה שאלות פתוחות - דבר שיכול ליצור בעיות תאימות. למשל: התקן מציין שהתוכן של רשומה יכול להיות HTML או טקסט - אך לא מגדיר דרך לומר במה השתמשו בפועל. על הצרכן לעבור על הטקסט, לחפש תגי HTML ומהם להסיק מהו הפורמט. חובבני משהו.
יתרה מכך, מפתח הפורמט מסר את הזכויות עליו (גרסה 2.0) לאוניבסיטת הארוורד וזו לא הואילה לפתוח את התקן או לשפר אותו בצורה מורגשת. מאז התקן "נעול".

סיבות אלו הספיקו ליצור צורך הולך וגובר בתקן חלופי ובעקבותיו הוגדר פורמט ה Atom: פורמט מוגדר היטב, בעל תקינה סטנדרטית של IETF (עוד גוף תקינה שעוסק באינטרנט). התקן זכה לאימוץ מתוקשר ע"י גולגל וכחלק מ AtomPub הוא אומץ ע"י מערכות תוכנה רבות.

המודל הבסיסי של אטום הוא פשוט למדי, פיד המכיל מספר רשומות:


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

הנה דוגמא אמיתית של קובץ Atom מינימלי (הכולל רשומה אחת):



<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">

  <title>Example Feed</title> 
  <link href="http://example.org/"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author> 
    <name>John Doe</name>
  </author> 
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <entry>
    <title>Atom-Powered Robots Run Amok</title>
    <link href="http://example.org/2003/12/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
  </entry>

</feed>

אטום מחייב במינימום את השדות שיש בדוגמא זו (Author וכו). זוהי החלטה דיי הגיונית לפורמט של פיד חדשות/בלוג.
הערה קטנה: בדוגמא למעלה הרשומה כוללת שדה Summary. אטום מחייב או Summary או Content (התוכן המלא).

כאשר קובץ הפיד (סיומת .xml. או atom.) יושב על שרת ווב - כל שיש לעשות על מנת לקרוא את תוכנו (עבור Feed Reader כדוגמת Outlook או Google Reader) הוא לבצע קריאת Http get פשוטה לכתובת הפיד, לקבל את הקובץ שלמעלה ולהציג אותו בצורה יפה.

Atompub
AtomPub מוסיף מימד של עריכה לפיד, ע"פ עקרונות ה REST ומאפשר לבצע פעולות CRUD שונות:

אם ארצה להוסיף רשומה לפיד, פשוט אשלח Http Post לכתובת הפיד, המכילה XML עם הרשומה להוספה וכל השדות המתאימים.
תזכורת: פעולת POST ב REST משמעה: "שלח מידע למשאב קיים". הפיד קיים ואנחנו שולחים לו עוד Entry והוא מוסיף אותו לפיד.

להלן הפעולות המוגדרות בתקן (ניתן להרחיב):
על פיד (ליתר דיוק Collection - עוד מעט אסביר) ניתן לבצע:
       GET כדי לקרוא אותו
       PUT על מנת להוסיף רשומה.
על רשומה (ליתר דיוק Member - פריט) ניתן לבצע:
      GET (קריאת רשומה בודדת)
      PUT (עדכון רשומה)
      DELETE (מחיקת רשומה).
על Service Document ניתן לבצע:
      GET.

מדוע אנחנו מדברים על Collection ו Member ולא על פיד ורשומה? מהו ה Service Document??

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

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

Service, או בעצם ה Service Document, הוא מסמך המתאר מספר אוספים (Collection) הקשורים לעולם זהה (Service). המסמך מחלק אותם לקבוצות הנקראות Workspaces - אין להם משמעות רבה.

הנה המודל של AtomPub בצורה ויזואלית:



עקרון של REST שאני רוצה להזכיר הוא Hypermedia Transformations. מה שעומד מאחורי השם המפחיד הזה הוא הרעיון לפיו בכל רשומה, (כלומר: בכל פריט. אדבר AtomPub) יש קישורים לפעולות האחרות האפשריות כגון האפשרות לעריכת פריט. הנה דוגמא:

<entry>
  <title>Some Report</title>
  <link href="http://host/products/some_report.atom"/>
  <link href="http://host/products/some_report.atom“ rel="edit"/>
  ...


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

אם אתם רוגזים בלבכם עד כמה שזה בזבזני - יש לי שני דברים לומר לכם:
א. אתם כנראה צודקים.
ב. נוסיף קצת פרספקטיבה: תקני *-WS הם בזבזניים משמעותית יותר. כלומר - אנחנו משתפרים.

מעבר לצרכים הבסיסיים (פעולות CRUD)
AtomPub מכיל יכולות נוספות, אגע בעיקריות:

Paging
ברור שאוסף פריטים יכול להיות דיי ארוך ואנו לא תמיד נרצה לקבל (או לשלוח - בצד השרת) את כל הרשימה - לפני שברור שזקוקים לכולה. אולי היא ארוכה מאוד וכוללת אלפי פריטים? ב AtomPub יש מנגנון Paging (השם הרשמי הוא Partial Lists) שנשלט ע"י צד השרת - הוא מחליט כמה פריטים להעביר בכל Chunk. מסמך האטום שיחזור יכיל קישור עם rel של next האומר "אם אתה רוצה עוד - גש ללינק הבא":

<link rel="next" href="http://example.org/entries/2" />

למפתחי UI של מערכות סגורות הבחירה לתת לצד השרת להכתיב את גודל ה paging יכולה להראות קצת תמוהה - הרי ה UI יודע הכי טוב מה הוא רוצה. אולם, חשבו REST ועל החשיבות של דפים אחידים על מנת להשתמש ב caches (של HTTP) - יש פה פוטנציאל ממשי.
השרת יכול גם להחליט אם הוא מותיר גם ללכת אחורה (קישור Pervious) או לקפוץ להתחלת או סוף האוסף. אם דיברנו על ההבדלים בין אוסף (collection) לפיד (של פורמט Atom) אז אוסף הוא הסט השלם והפיד הוא view או page שקיבלנו בכל פעם.

Categories
ב Atom (אופס, דילגנו על זה כבר) וגם ב AtomPub יש עניין של קטגוריות. אלו בעצם תגיות (tags) על הרשומות או הפריטים באוסף. יש גם "מסמך קטגוריות" שמגדיר את כל הקטגוריות (או תגיות) הקיימות במערכת. דיי בנאלי ולא כ"כ שווה להתעכב על זה לדעתי.

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

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

עוד נקודה מעניינת היא שיכולת זו מעודדת לייצר פידים שונים המתארים אותם פריטים - עם שוני קטן שהוא הפריטים שבעריכה. מימושים רבים המבוססים על AtomPub נוטים להגדיר מספר מצומצם של שאילותות קבועות (פידים) עם URI קבועים אותם ניתן לתשאל. זו גישה שמתאימה ל REST ולניצולת טובה של ה caches אך היא קצת מגבילה את הלקוח ולעיתים דורשת ממנו "לבחור את פיד-הבסיס" ועליו לעשות עוד מעבר של "פילטור ידני". זו לא גישה רעה - יש פה  tradeoff. בהמשך נראה ש ODATA דוגל בגישה אחרת.

מדיה (Media Library Entries (MLE
כפי שציינו Atom הוא פורמט מבוסס XML. מה קורה אם אני מעוניין לנהל מידע שלא יכול להיות מתואר בצורת XML? כגון תמונות, מסמכים (נאמר PDF) וכו'? כמובן שאפשר לעטוף את המידע הבינרי ב XML בעזרת בלוקים של CDATA - אך אז פעולת Http Get של פיד תגרום לקריאת כל התוכן הבינרי של כל הרשומות - כמות גדולה של נתונים.
הפתרון של AtomPub הוא לייצר אוספים של רשומות מדיה (מידע בינרי) רשומות אלו נקראות Media Members.

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

ההחלטה של AtomPub היא להחזיר את שדות אלו למיטב יכולתו של השרת, כנראה על בסיס המידע שיש לו על הפיד, וסביר שקצת יפוברקו. רשומות ה Media Library Entries הן בעצם מצביע לקובץ המדיה. הרשומות יכללו לינק אחת לעריכת ה MLE - כלומר ה metadata (בצורת "rel="edit) ו URI נפרד לעריכת קובץ ה מדיה עצמו (בצורת "rel="media-edit)



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

2012-01-30

הו-נתונים! (Odata)


אם אתם מתכננים לבנות מערכת על פי עקרונות ה REST, הפופולאריים למדי היום, כדאי להכיר עוד כמה כלים שיכולים לעזור במלאכה. אני מניח שאתם מכירים באופן כללי מהו REST. אם לא, תוכלו לקרוא פוסטים קודמים המספקים סקירה טובה כאן (מבוא) וכאן (קצת יותר לעומק). REST בפני עצמו פותח מרחב עצום של אפשריות מימוש. באיזה דרך אתם תבחרו? האם תתקלו בבעיות שאחרים נתקלו בהן כבר? איך תדעו שאתם לא נופלים ל pitfall נפוץ? איך תדעו שמה שעשיתם הוא טוב? איך??

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

מקור: http://everythingsdynamic.blogspot.com

בשרשרת פוסטים זו אדבר על ODATA (קיצור של Open Data) שנראה כיום התקן המבטיח להחלפת נתונים בין מערכות ברשת, המבוסס על עקרונות ה REST. התקן פשוט לשימוש פשוט, אך יש בו גם כמה מורכבויות. הוא מתאים בעיקר למצבים בהם הנתונים אותם אתם חושפים הם מורכבים ו/או יש לכם מספר צרכנים עם צרכים שונים. אם אתם זקוקים ל 3 שאילתות קבועות בין 2 מערכות - ODATA יהיה overkill בשבילכם. פשוט שלחו XML (או JSON) על גבי HTTP וטפלו בכמה שגיאות נפוצות.

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

אתחיל ב Atom Publishing Protocol (או בקיצור AtomPub, נקרא גם APP - אך זהו שם מבלבל) - תקן שנוצר עבור פרסום נתונים של בלוגים או אתרי חדשות וזכה לאימוץ ע"י מערכות מתחומים שונים לחלוטין.

גוגל, אחת המאמצות, ראתה שהתקן לא מספיק ושכל מוצר שלה (Calendar, Documents, Gmail) יצר כמה תוספות. היא אספה את התוספות השונות, סידרה אותן ויצרה את GDATA פרוטוקול מורחב המבוסס על AtomPub. לרוע המזל GDATA לא היה בשל כ"כ והיו בו מספר בעיות משמעותיות, אך עם הזמן גוגל מעדכנת ומשפרת את התקן. נדבר גם עליו.

מייקרוסופט, אחת הפטרוניות המרכזיות של תקני ה WS-* (תקני ה Web Services, אשר REST בא להחליפו) ראתה את התקנים שלה נזנחים ע"י חלקים הולכים וגוברים של התעשייה ולא רצתה להשאר מחוץ לתמונה. היא יצרה תקן בשם ODATA עליו נדבר. היא הבינה שהיא הצטרפה לחגיגה קצת מאוחר. בצעד חריג, עבור מייקרוסופט, היא פתחה את התקן ושחררה ספריות בג'אווה, ג'אווהסקריפט, PHP ועוד המאפשרות להשתמש בו. יש גם דיבורים על מסירת התקן לגוף תקינה חיצוני ובלתי תלוי - אך זה עדיין לא קרה.

כמובן שיש עוד שחקנים: יאהו מנסה לקדם תקן בשם DataRSS (ללא הצלחה רבה) וה W3C מנסה לקדם תקן בשם Linked Data המבוסס על פורמט בשם RDF - אך נכון להיום התקן שתופס הכי הרבה תאוצה הוא דווקא ODATA של מיקרוסופט והוא מאומץ גם ע"י חברות אינטרנט (נטפליקס, איביי) וגם ע"י ארגוני ענן (יבמ, סאפ).


ODATA
OData הוא קיצור ל Open Data Protocol. אם מחפשים עליו חומר כדאי לשים לב ש Open Data הוא מושג רעיוני של שיתוף מידע באינטרנט. חפשו ODATA או Open+Data+Protocol כדי לקבל תוצאות טובות יותר.

OData פועל על גבי HTTP ומבוסס על עקרונות ה REST. בעצם הוא מבוסס על AtomPub שמבוסס גם על Atom וגם על REST. מבולבלים? הנה לנוחיותכם דיאגרמת Venn שתסביר את העניין:


  • POX הוא הרעיון של העברת נתונים על גבי HTTP בפורמט XML (כלשהו).
  • REST היא ארכיטקטורה מבוססת Resources המבוססת על POX, אך מציבה חוקים נוספים => כלומר, מקרה פרטי של POX. הסתייגות קטנה היא ש REST לא מחייב XML.
  • Atom הוא פורמט מבוסס XML לתיאור Web Feed - רשימת פריטי חדשות, פוסטים בבלוג וכו'. הפורמט המקביל והמוכר קצת יותר הוא RSS.
  • AtomPub הוא מימוש REST המבוסס על פורמט ה Atom שמאפשר לא רק לקרוא Web Feeds אלא גם להוסיף / לעדכן ולמחוק אותם. הוא מוסיף גילוי ועוד כמה יכולות. 
  • ODATA (כמו GDATA) מבוסס על AtomPub (ומכאן גם על Atom) ומספק סט כלים עשיר יותר של כלים.

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

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

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

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

בפוסט ההמשך אדבר על AtomPub וכיצד אפשר להשתמש בו למימושי REST פשוטים