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

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

מה זה API?

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

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

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

עקרונות מרכזיים של עיצוב API

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

חוסר סובלנות

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

המונחים:

משאבים הם הפשטות הבסיסית ב REST. A משאב יכול להיות אובייקט, אוסף של אובייקטים, או אפילו תהליך. כל משאב מזוהה ייחודי על ידי מאמת משאבים אחיד (URI) URI צריך לייצג את המיקום של משאבים בהיררכיה. לדוגמה, FLT:0 מייצג אוסף של משאבי משתמשים, בעוד ש-F:1LT מייצג אוסף ספציפי של פעולות על ידי משתמשים מבוצעים באמצעות פעולות HTTP, אשר הם פעולות סטנדרטיות למיפוי שיטות סטנדרטיות.

שימוש בשיטות HTTP

REST ממנף את הסימנטיקה של שיטות HTTP סטנדרטיות באופן אחיד:

  • (ב) ויקרא י"ד: "וַיְּהָעָשֶׂה עַכְתָּעָה" (שם כ"ד).
  • (ב) ,0) , ⁇ (לא מבדיל).
  • (ב) ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇
  • (ב) ,0) ,PATCHFLT:1 , עדכון חלקי של משאב (לא בהכרח idempotent).
  • (ב) ,0) , ⁇ (ב) , (הופנה מהדף [[המאה ה-1]]

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

ייצוג

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

ממשק אחיד

הממשק המדוייק הוא התכונה הייחודית ביותר של REST.It מבטל את הלקוח מהיישום הפנימי של השרת.מגביל זה מורכב מארבעה תת-שכבות:

  • (ב) ויקרא י"א: "כל אחד מהם הוא מקור ל[[המאה ה-20]]" (בראשית כ"ד).
  • (ב) ,0) ניצול משאבים באמצעות ייצוגים של ההרחבה: לקוחות מניפולטיביים משאבים על ידי שליחת ייצוגים (למשל, בקשה ל- PUT עם גוף JSON).
  • (ב) [ה]כל בקשה ותגובה מכילה מספיק מידע כדי להבין (למשל, ראשי תיבות של מדיה, קודים סטטוסים).
  • (FLT:0)Hypermedia כמנוע של מדינת יישום (HATEOAS) 1FIRLT:1 - ה- API מספק קישורים שמדריכים לקוחות לגלות פעולות זמינות באופן דינמי, בעוד HATEOAS הוא לעתים רחוקות לחלוטין, הבנה זה עוזר לך לעצב API כי הם יותר לגלות ופחות מערערער.

שאלות נפוצות של API

איך צריך לבנות נקודות סוף?

עיצוב קצה הוא אחד ההיבטים המפוקחים ביותר של עיצוב API.הפרקטיקה הטובה ביותר המקובלת האוניברסלית היא להשתמש ב-FLT:0plural nounscioFLT:1 עבור אוספים משאבים ולהימנע מפועלים ב-URIs.

  • (FLT:2) - אוסף של משתמשים
  • (FLT 3: 3) משתמש יחיד
  • (FLT:4) - הוראות שייכות למשתמש ספציפי
  • (ב) ,5 , פקודה אחת

(הדגשה צריכה להיות מוגבלת) לניסוח של יותר משניים או שלושה רמות, קשה לקרוא ולשמור על כך שמערכות יחסים מורכבות, לשקול שימוש בפרמטרים של שאילתה או משאבים ייעודיים.הימנעות מפעולות כמו FLT:6 משום ששיטת HTTP כבר מעבירה את הפעולה.

איך להצמיד שגיאות?

תגובות שגיאה חייבות להיות אינפורמטיביות ועקביות, השתמש בקוד הסטטוס HTTP הנכון:

  • (ב) [ה]: [ה], [ה], [ה], [ה], [ה], [ה],], [ה], [ה], [ה],], [התבקשה], נעדרת שטח, לא חוקי].
  • (ב) [15] ,9.10.10.10.10.10.10.10.10.10.10.10.1 לא מורשה
  • (ב) [15] ,9.
  • (ב) לא קיים כלל (ב)
  • (ב) ,0,09 ניגודים (הופנה מהדף ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ).
  • (ב) [15] ,2 ,2 ,לא ניתן לעבד את ה-AtityFIRLT:1 , מוטציות בגופות הבקשה.
  • (ב) ,0500 ,500 Internal Serverrough ErrorFLT:1 - כישלון השרת הבלתי צפוי.

בנוסף לקוד הסטטוס, גוף התגובה צריך לכלול מבנה עקבי.תבנית נפוצה היא:

{
 "error": {
 "code": "USER_NOT_FOUND",
 "message": "User with ID 42 not found.",
 "details": "..."
 }
}

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

מה לגבי גירסה?

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

  • (ב) [ה]: [ה], [ה], [ה],] [ה], [ה],] [ה]], זוהי הגישה הפופולרית ביותר, משום שהיא מפורשת וקלה לתוואי.
  • (ב) [המנהיג], [ה], [ה], [ה], [ה],] ב[[המאה ה-21], יש צורך בבקשה אישית (לדוגמא:] ב[החל] ב[ה], אך הוא דורש מלקוח לקבוע את ראש הממשלה כראוי.
  • (ב) פרמטר פרמטר פרמטר פרמטרים (FLT:0) פרמטר פרמטר פרמטר פרמטר (FLT: 12) הוא בדרך כלל מרתיע כי הוא מכווץ מיתרי שאלות ויכול להפריע לשחיקה.

גרסה URI היא הפשוטה ביותר עבור רוב הקבוצות.המשך גרסאות לתקופה סבירה (לפחות שנתיים) ולהניח אותן באמצעות תקשורת ברורה.

כיצד ליישם את Pagination, סינון ומיין?

נקודות קצה (למשל, FLT) יכולות להחזיר אלפי רשומות ללא דמיונות, צפי ביצועים ורשתות מעל בלונים.

  • (ב) [15] ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇ ⁇
  • (ב) [ה]:0] ,[דרוש מקור] [ב]: [ה], [ה], [ה], [ה], [ה], [ה], [ה]], [ה], [ה], למשל, [ב[[1924]]],]
  • (ב) ,0) ,(ה) ,(ה) ,ההנחה עם פרמטרים כגון FLT:20 או FLT:21 עבור צו יורד.

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

איך להגות Authentication and Authorization?

REST APIs הם חסרי מדינה, ולכן האימות חייב להתרחש עם כל בקשה.הגישה הנפוצה ביותר היא להשתמש ב-FLT:0.10.1 אסימונים של אסימונים (FLT:22 ראש הממשלה 2.OAuth 2.0 היא תקן התעשייה עבור אבטחת API פנימית, מפתחי API (מנוהלים בראש מותאם אישית) הם לעתים מספיקים, אבל הם מציעים אבטחה חלשה יותר כי מפתח לא ניתן לבטל את עצמו בקלות ללא שינוי מפתח.

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

חוסר יכולת

(ה) ,הההבאה (ב) היא זו ש[ה], ו[ה], ב[[המאה ה-20]], [[המאה ה-20]], [[1924]], [[1924]]]]]], [[1924]]]]]], [[1924]]]]]]]], [[1924]]]]]]]]]], [[1924]]]]]]]], [[1924]]]]]]]]]], [[1924]]]]]]]]]]]], [[1924]], [[1924]]]]]]]], [[1924]]]]]]]]]]]]]]]]]]]], [[1924]], [[1924]]]]]]]], [[1924]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]

איך לנהל את Caching?

⁇ משפר את הביצועים ולהפחית את עומס השרתים (HTTP caching) נשלט על ידי ראשי התיבות כגון (FLT:24,FLT:25, FLT:26, ו-FLT:27 עבור ממשקי API ציבוריים, להגדיר חיים מתאימים על משאבים יציבים.

לשנאה או לא לשנאה?

HATEOAS (Hypermedia as the Engine of Application State) מצוטט לעתים קרובות כמתאמת מפתח של REST, אך לעיתים רחוקות הוא מאומצ במלואו בפועל.הרעיון הוא שייצוג משאבים כולל קישורים לפעולות קשורות, ומאפשר ללקוחות לנווט את ה- API ללא ידע קודם.לדוגמה, משאב משתמש עשוי לכלול FLT:30 בעוד לא חובה, הוספת קישורים לתגובות שלך יכול לגרום ל- API לגלות יותר ולהפחית את היחסים הדרושים עם שרת.

Best Practices for REST Design

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

שקיפות מעל הכל

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

מספק מסמך מקיף

תיעוד טוב הוא חלק בלתי נפרד מ- API. Tools כמו Swagger/OpenAPI, ⁇ :0DirectusFLT:1 (אשר כולל הדור אוטומטי של תיעוד API), ואוספים Postman עוזרים למפתחים להבין את נקודות הקצה במהירות.בקשת מסמכים/דוגמאות אחראיות, קודים, מגבלות וזרימי שגיאות.

קודים סטנדרטיים של HTTP

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

כל נקודת קצה

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

עיצוב הצרכן

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

תוכנית לפיתוח

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

מסקנה

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

המשך ללמוד את ההנחיות עיצוב API של ה-APR:0 (FLT:2) ו-(JSON:API SpecationFLT 3) לתובנות עמוקות יותר, כפי שאתה מעצב את ה- API הבא שלך, לשמור על מגבלות של חוסר יציבות, אוריינטציה משאבים, וממשק אחיד בראש, אבל גם איזון עם פרגמטיות.