שיטות מומלצות להוספת ספק סוגים

בדף הזה מוסברות שיטות מומלצות ליצירת API חדש להוספה ל-Deployment Manager כספק סוגים, או להוספה של API קיים כספק סוגים.

באמצעות Deployment Manager אפשר להוסיף ממשקי API כספקי סוגים כדי לחשוף את משאבי ה-API כסוגים שאפשר להפעיל בהגדרה שלהם. כדי להקל על התהליך, כדאי להשתמש בשיטות המומלצות האלה כשמגדירים או יוצרים API.

פיתוח API חדש

אם אתם יוצרים API חדש שאתם מתכוונים לשלב עם Deployment Manager, כדאי להשתמש בשיטות המומלצות האלה.

מומלץ להשתמש בשיטות סטנדרטיות של יצירה, קריאה, עדכון ומחיקה (CRUD) ולהימנע משיטות בהתאמה אישית

אם אפשר, מומלץ להימנע מיצירת שיטות מותאמות אישית. מומלץ להשתמש בשיטות REST רגילות כמו GET,‏ POST,‏ PUT ו-DELETE. השיטות האלה מזוהות על ידי Deployment Manager ואפשר למפות אותן באופן אוטומטי.

ב-Discovery APIs, צריך לתת שמות לשיטות ה-API בהתאם למיפוי הבא:

שיטת REST שמות מומלצים ל-API
POST create או insert
GET get
PUT update
DELETE delete

במפרטים של OpenAPI, אי אפשר לתת שמות ל-methods של ה-API ששונים מהשמות של ה-methods הרגילות של REST.

שימוש בנתיבי משאבים צפויים

במפרטים של OpenAPI, ‏ Deployment Manager תומך בשני אופנים לזיהוי ממשק RESTful. האפשרות הראשונה היא אם כל שיטות ה-REST של משאב מסוים שייכות לאותו נתיב משאב:

/foo/{name}
  post:
  get:
  delete:
  put:

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

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

אבל הדוגמה הבאה לא תקינה כי היא מתייחסת לשני משאבים שונים מנקודת המבט של Deployment Manager:

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

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

foo/create
  post:

foo/delete
  delete:

הערך הזה לא תקין מנקודת המבט של Deployment Manager כי הוא לא יכול לזהות את הממשק RESTful.

שימוש בשמות עקביים בממשק

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

לדוגמה, אם יש לכם פרמטר בשם email בגוף הבקשה של בקשת POST, אל תקראו לאותו פרמטר emailAddress בבקשת PUT.

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

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

בנוסף, צריך להשאיר את גוף הבקשה לשיטות POST ו-PUT ללא שינוי. בשיטות GET ו-DELETE, רק הנתיב רלוונטי כי אין גוף בקשה לשיטות האלה.

שילוב של API קיים

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

  • משתמשים ב-API wrapper עבור ממשקי API שאינם מבוססי REST.

    אם API קיים הוא לא API ל-REST, אפשר ליצור wrapper ל-API כדי לחשוף רק את שיטות ה-REST.

  • אם ה-API כמעט מבוסס על REST, צריך לזהות ולעדכן את ה-API.

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

  • תמיד צריך מיפוי קלט לערכים שנוצרים בשרת.

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

המאמרים הבאים