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

1. איך עובדים דפי אינטרנט

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

את האינטרנט, או לפחות את הטכנולוגיות שמפעילות אותו, המציא טים ברנרס לי בשנת 1991 והטכנולוגיה הראשונה שהוא המציא נקראת HTTP (ראשי תיבות של Hyptertext Transfer Protocol). זהו פרוטוקול, כלומר שפה, שנועדה להגדיר איך מחשבים מעבירים ביניהם דפים ברשת האינטרנט. הפרוטוקול מגדיר בגדול שכל מחשב יכול להחזיק "דפים" ולכל דף יש מזהה. המזהה נראה כמו שם קובץ על מערכת יוניקס לדוגמה /wiki/HTTP, /en/api/client-sdks או /arunsupe/semantic-grep. פרוטוקול HTTP מגדיר שאם מישהו רוצה לבקש דף ממחשב מרוחק הוא שולח הודעה שמורכבת מהמילה GET ואחריה שם הדף למשל:

GET /en/api/client-sdks/

טים ברנרס לי גם המציא דפדפן אינטרנט שאפשר לו לקרוא את הדפים האלה (שהיו כתובים בפורמט HTML) וקצת אחריו אנשים אחרים המציאו דפדפני אינטרנט נוספים והרחיבו את הפורמט של הדפים. ב 1996 ככל שיותר אנשים כתבו דפי אינטרנט עלה הצורך בביצוע פעולות דרך דפי האינטרנט והומצא אלמנט הטופס. בשביל להגיש טפסים טים ברנרס לי עדכן את פרוטוקול HTTP והוסיף פקודה בשם POST. בשביל להגיש טופס עדיין היה צריך לציין את הנתיב להגשה ובדרך כלל צורף לבקשה מידע מהטופס. כך נראתה בקשת POST שנוצרה מטופס:

POST /cgi-bin/subscribe.cgi HTTP/1.0
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 27

name=Alice+Smith&email=alice%40example.com

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

לאורך השנים נוספו לפרוטוקול HTTP פעלים נוספים והיום הפרוטוקול מונה את הפעלים GET, HEAD, OPTIONS, TRACE, POST, PUT, PATCH, DELETE. קוד בצד השרת, כלומר במחשב שמקבל את הבקשה, אחראי על טיפול בבקשה. הקוד מקבל את הפועל, את הנתיב, את הכותרות ואת גוף הבקשה וצריך לבצע פעולה ולהחזיר תשובה לדפדפן. לפעמים התשובה תהיה דף אינטרנט, לפעמים היא תהיה תמונה ולפעמים הפניה לעמוד אחר.

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

2. עכשיו בואו נוסיף אפליקציה

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

<h1>hello world</h1>

מתאר שורת כותרת עם הטקסט hello world. הבלוק:

<h1>hello world</h1>
<p>HTML was also invented by Tim Berners Lee along with HTTP and the first web browser</p>

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

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

3. הפיתרון - JSON

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

ג'ייסון, שזה קיצור ל JavaScript Object Notation, הוא שפה שהומצאה על ידי דאגלס קרוקפורד בשנת 2,000. בניגוד ל HTML שמתארת מסמכים, ג'ייסון היא שפה לתיאור אוביקטים כלומר מידע מובנה, אבל הייתרון הגדול שלה הוא שקל מאוד למחשבים לקרוא אוביקטי JSON - הרבה יותר קל מאשר לקרוא קבצי HTML. הנה דוגמה לקובץ JSON שמתאים לקובץ ה HTML שהראיתי קודם:

{
    header: "hello world",
    text: "HTML was also invented by Tim Berners Lee along with HTTP and the first web browser"
}

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

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

4. מה אפשר לעשות עם REST API

רגע, אז מאיפה הגיעה לפה המילה REST? אם API הוא קיצור של ממשק תכנותי ומייצג חיבור בין שתי מערכות המילה REST היא גם ראשי תיבות הפעם של Representational State Transfer. את השם הזה המציא רוי פילדינג בשנת 2000 כדי לייצג שיטת עבודה מסוימת של ממשקים בין מערכות. בחיבור מסוג REST API הנתיב, שזה שם הקובץ בבקשת ה HTTP, מייצג משאב. תשובת השרת מייצגת את התוכן או ה State של אותו משאב. אני חושב שדוגמה קטנה תעזור להבהיר כאן את המושגים - נניח שאנחנו בונים מערכת לניהול ספרים בספריה והמערכת מאפשרת להציג פרטים על ספרים לפי מזהי הספר. ספרים מזוהים על ידי מזהה שנקרא ISBN ולכן ניתן להשתמש ב ISBN כדי לייצג "ספר". נתיב לדוגמה במערכת הספרים שלנו יכול להיות:

/book/0764363778

בקשת רשת בשפת HTTP למשאב זה יכולה להיות:

GET /book/0764363778

והתשובה שהשרת יחזיר עשויה להיות:

{
  "name": "JavaScript: The Good Parts",
  "author": "Douglas Crockford",
  "rating": 4.4,
  "price": "16$"
  "instock": 10
}

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

PUT /book/1234567890

{
  "name": "The Art of Fiction",
  "author": "Jane Doe",
  "price": 19.99,
  "rating": 4.5,
  "instock": true
}

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

1. פעולת GET על המשאב, בלי לציין מזהה משאב, למשל GET /books מחזיר אינדקס של הפריטים כלומר את כל הספרים.
2. פעולת GET על המשאב עם ציון מזהה פריט יחזיר מידע על אותו פריט, למשל GET /books/123 יחזיר פרטים על ספר שהמזהה שלו הוא 123.
3. פעולת POST על המשאב, בלי לציין מזהה, תיצור פריט חדש מאותו משאב. למשל POST /books תיצור ספר חדש.
4. פעולת PUT על המשאב עם ציון מזהה תעדכן את הפרטים של אותו משאב לדוגמה פעולת PUT /books/123 תעדכן את הפרטים של ספר 123.
5. פעולת DELETE על המשאב עם ציון מזהה מוחקת את הפריט, לדוגמה DELETE /books/123 תמחק את ספר מספר 123.

5. עוגיות והזדהות

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

הודעת HTTP כוללת בסך הכל 3 חלקים בהם אפשר לכתוב מידע: שורת המזהה שכוללת את הפועל והנתיב עליהם אנחנו מדברים, בלוק הכותרות ובלוק תוכן ההודעה. נתוני הזדהות נשלחים בבלוק הכותרות.

יש שני סוגים של נתוני הזדהות שאנחנו יכולים למצוא בכותרות של בקשות HTTP. סוג אחד נקרא Cookie וזו כותרת שנראית כך:

GET /docs/introduction HTTP/1.1
Host: ai-sdk.dev
accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7
accept-language: en-US,en;q=0.9
cache-control: no-cache
cookie: ko_id=7827ad98-2a94-440f-be5b-6dd5cfd84161; _hp2_id.3132448398=%7B%22
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36

הבקשה בדוגמה מנסה למשוך משאב עם המזהה /docs/introduction ומעבירה לשרת מספר כותרות HTTP. אחת הכותרת נקראת cookie והיא מכילה ערך שקצת קשה לקרוא. זה בסדר אנחנו לא צריכים לקרוא אותו מי שצריך לקרוא אותו זה שרת ה Web. השרת קורא את הערך ומבין ממנו מי הבן אדם שמולו. איך ערך ה cookie מתורגם לזהות הגולש אתם שואלים? פה נכנס לתמונה תהליך ההזדהות. משתמש ממלא טופס עם שם משתמש וסיסמה, השרת בודק שהסיסמה נכונה ורושם בבסיס הנתונים ליד שם המשתמש ערך אקראי שנקרא מזהה Session, את הערך האקראי הזה הוא מחזיר באותה תשובת HTTP שנשלחת אחרי מילוי הטופס. מכאן והלאה הדפדפן יצרף את אותו ערך אקראי לכל בקשה בתור כותרת ה HTTP שנקראת cookie. השרת יקבל את הערך האקראי הזה, יסתכל בבסיס הנתונים עבור איזה משתמש הוא נוצר וכך ידע מי שלח את הבקשה.

מערכות רבות לא מציגות טפסים ב HTML ובכלל לא עוברות דרך דפדפן. עבורן נוצר מנגנון נוסף שהוא כותרת בשם Authorization. במערכת כזו נבצע איזשהו תהליך הזדהות באמצעות קריאת HTTP POST עם מזהה מסוים (ממש דומה להגשת טופס), גם כאן השרת יאמת את המשתמש, יגריל ערך אקראי וישמור אותו בבסיס הנתונים וישלח חזרה את אותו ערך למערכת שפנתה אליו. בבקשות הבאות אותה מערכת תצרף כותרת HTTP בשם Authorization ותשים בה את המזהה שהיא קיבלה. בקשה כזו תיראה כך:

POST /book/1234567890/ HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.dGVzdF91c2VyX2RhdGE.abc123dummySignature
Content-Type: application/json
Content-Length: 109

{
  "name": "The Art of Fiction",
  "author": "Jane Doe",
  "price": 19.99,
  "rating": 4.5,
  "instock": true
}

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

6. סיכום

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