איך בונים REST API נכון - העקרונות שכל מפתח צריך להכיר¶
כל מי שלומד פיתוח צד שרת מגיע בשלב מסוים לרגע הזה - אתם בונים את ה-API הראשון שלכם, הוא עובד, אתם שולחים בקשה ומקבלים תשובה, ואתם בטוחים שסיימתם. אבל "עובד" ו"בנוי נכון" הם שני דברים שונים לגמרי, וההבדל ביניהם הוא בדיוק מה שמפריד בין קוד של מתחיל לקוד של מפתח שיודע מה הוא עושה.
בואו נעבור על העקרונות שבאמת חשובים, בלי הצפה של מונחים.
תזכורת קצרה - מה זה בכלל REST¶
REST הוא בעצם קבוצת כללים מוסכמת לאיך API אמור להתנהג, כדי שמפתחים אחרים (ואתם עצמכם בעוד חצי שנה) יוכלו להבין אותו בלי מסמך הסברים ארוך. הרעיון המרכזי הוא שכל דבר במערכת שלכם הוא "משאב" - משתמש, מוצר, הזמנה - ויש לו כתובת קבועה, ואתם מבצעים עליו פעולות דרך פעלי HTTP מוכרים.
זה נשמע מופשט, אז בואו נעבור לדברים המעשיים.
עקרון 1 - כתובות הן שמות עצם, לא פעלים¶
הטעות הכי נפוצה שרואים בקוד של מתחילים היא כתובות כמו /getUsers או /createNewOrder. זו בעצם חשיבה מהעולם הישן, שבו כל כתובת היא פונקציה. ב-REST הכתובת מתארת את המשאב, והפועל שאתם משתמשים בו (GET, POST, וכו') הוא זה שקובע מה קורה.
אז במקום /getUsers פשוט כותבים /users, ושולחים אליו בקשת GET כדי לקבל רשימה, ובקשת POST כדי ליצור משתמש חדש. אותה כתובת, שתי פעולות שונות, לפי הפועל.
עקרון 2 - תשתמשו נכון בפעלי HTTP¶
- GET - קריאת מידע בלבד, בלי לשנות שום דבר במערכת
- POST - יצירת משהו חדש
- PUT - עדכון מלא של משאב קיים
- PATCH - עדכון חלקי של משאב
- DELETE - מחיקה
זה נשמע בסיסי, אבל מפתחים רבים מתעצלים ומשתמשים ב-POST לכל דבר, כולל מחיקות ועדכונים. זה עובד טכנית, אבל זה הופך את ה-API שלכם לבלתי צפוי למי שמנסה להשתמש בו.
עקרון 3 - status codes הם לא קישוט, הם מידע¶
אחת הטעויות הכי נפוצות שאני רואה היא API שמחזיר קוד 200 (הצלחה) על הכל, כולל שגיאות, ומצפה מהצד השני לקרוא את גוף התשובה כדי להבין שמשהו נכשל. זה הופך את חיי המפתחים שמשתמשים ב-API שלכם לגיהנום.
תשתמשו בקודים בצורה נכונה - 200 להצלחה, 201 כשנוצר משהו חדש, 400 כשהבקשה עצמה שגויה, 401 כשאין הרשאה, 404 כשהמשאב לא נמצא, 500 כשמשהו קרס בשרת. זה נשמע כמו פרט טכני קטן, אבל זה ההבדל בין API שקל לעבוד איתו לבין אחד שגורם לכולם לקלל אתכם.
עקרון 4 - עקביות חשובה יותר מיצירתיות¶
אם החלטתם שהשדה בתשובה נקרא user_id, תשמרו על השם הזה בכל ה-API, ולא תחליפו באמצע ל-userId או id. אם החלטתם שכל שגיאה מוחזרת בפורמט מסוים, תשמרו על הפורמט הזה בכל מקום. מפתח שמכיר חלק אחד מה-API שלכם צריך להיות מסוגל לנחש נכון איך החלק הבא יתנהג.
עקרון 5 - אל תשכחו pagination¶
אם יש לכם משאב שיכול להכיל אלפי רשומות, כמו רשימת משתמשים, אסור להחזיר את כולן בבת אחת. זה יאט את השרת ואת הלקוח כאחד. תמיד תוסיפו מנגנון עימוד - להחזיר רק חלק מהתוצאות, עם אפשרות לבקש את החלק הבא. זה נראה כמו פרט קטן שאפשר "להוסיף אחר כך", אבל ברגע שיש לכם מסד נתונים אמיתי עם נתונים אמיתיים, זה כבר מאוחר מדי.
עקרון 6 - תחשבו על גרסאות מהיום הראשון¶
ה-API שלכם ישתנה. תמיד. הדרך הנכונה להתמודד עם זה היא לתת ל-API גרסה, בדרך כלל בכתובת עצמה, כמו /v1/users. כך כשתרצו לשנות משהו באופן שובר תאימות, תוכלו לפתוח /v2/users בלי לשבור את כל האפליקציות שכבר משתמשות בגרסה הישנה.
איפה לומדים את זה לעומק¶
כל העקרונות האלה נשמעים פשוטים כשקוראים עליהם, אבל היישום האמיתי שלהם קורה כשבונים API אמיתי, עם משתמשים אמיתיים, מסד נתונים אמיתי, ובעיות אמיתיות. בדיוק ככה אנחנו מלמדים את זה בקורס צד שרת - לא רק תיאוריה, אלא בניית API שלם מהיסודות, עם FastAPI, כולל כל הטעויות שכדאי לכם לעשות פעם אחת בסביבת לימוד ולא בפרויקט אמיתי.
ואם אתם באמצע בניית API ונתקעתם על החלטת עיצוב - איך לקרוא לכתובת, איזה קוד שגיאה להחזיר - זה בדיוק סוג השאלות שדנים בהן בדיסקורד שלנו.
לסיכום¶
REST API טוב לא נמדד בזה שהוא "עובד", הוא נמדד בזה שמפתח אחר יכול להסתכל עליו ולהבין מיד איך להשתמש בו, בלי לשאול אתכם שאלות. תשקיעו את המחשבה הזאת מההתחלה, כי לשנות מבנה API אחרי שכבר משתמשים בו זה הרבה יותר כואב מאשר לתכנן אותו נכון מהיום הראשון.