דרישות API לשילוב API

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

ל-API יש מסמך תיאור תקין

מסמך תיאור מתאר API ואת המשאבים שלו. אפשר לשלב ב-Deployment Manager רק ממשקי API שמגובים על ידי מפרט OpenAPI או על ידי מסמך תיאור Google Discovery. מידע מקיף על יצירת מפרט OpenAPI זמין במאגר OpenAPI GitHub.

יש גישה לנקודת הקצה (endpoint) של מסמך התיאור של ה-API

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

ממשק ה-API מקבל אימות בסיסי או OAuth2 אם הוא מתארח בשירותי Google מסוימים

בשלב הזה, Deployment Manager תומך באימות בסיסי (שם משתמש וסיסמה) ובאימות OAuth 2.0 לממשקי API מסוימים שמתארחים ב-Google Kubernetes Engine או ב-Google Endpoints. אתם יכולים להגדיר אימות לשימוש בחשבון השירות של הפרויקט.

מידע נוסף זמין במאמר בנושא יצירת ספק סוגים.

תמיכה בפעולות Create, ‏ Read, ‏ Update, ‏ Delete ‏ (CRUD)

ה-API המדובר צריך להיות API RESTful שתומך בפעולות CRUD. כלומר, יש שיטות שמבצעות:

  • יצירת פעולות – יצירת משאבים. זו חייבת להיות בקשת HTTP POST.
  • פעולות קריאה – קבלת מידע על משאבי API. זו חייבת להיות בקשת HTTP GET.
  • פעולות עדכון – עדכון משאב. זו חייבת להיות בקשת HTTP PUT
  • מחיקת פעולות – מחיקת משאבים. זו חייבת להיות בקשת HTTP DELETE.

ממשק API שתומך רק בפעולות CRUD חלקיות עדיין יפעל, אבל ההתנהגות תהיה שונה בהתאם לפעולות שזמינות.

תמיכה בבקשות GET תמיכה בבקשות CREATE תמיכה בבקשות UPDATE תמיכה בבקשות DELETE התנהגות מיוחדת של ה-API?
כן כן כן כן אין.
כן כן כן לא המשתמשים יכולים לנטוש משאב, אבל לא למחוק אותו.
כן כן לא כן כל שינוי במשאב קיים ייכשל. כדי לעדכן משאב, המשתמשים צריכים למחוק אותו וליצור אותו מחדש.
כן כן לא לא שתי ההתנהגויות שמתוארות למעלה.
כן לא כן כן אם API לא תומך בבקשות ליצירה, המשתמשים יכולים להוסיף משאבים קיימים לפריסה על ידי עדכון הפריסה באמצעות המדיניות ACQUIRE.
כן לא כן לא משתמשים יכולים להשיג משאב או לעדכן משאב אחרי שהוא הושג, אבל אי אפשר למחוק את המשאב.
כן לא לא כן המשתמשים יכולים למחוק משאב ולקבל משאב, או להוסיף משאב קיים לפריסה.
כן לא לא לא משתמשים יכולים להשיג משאב קיים או להסיר אותו באמצעות המדיניות ABANDON.

כל הפרמטרים של הנתיב והשאילתה נפתרים בהצלחה

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

כל פרמטר של נתיב או שאילתה עבור POST חייב להיות פרמטר עבור PUT

ההגדרה הבאה לא חוקית כי myParameter קיים עבור POST אבל לא עבור PUT:

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

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

בתרחיש האופטימלי, ה-API עשוי להיראות כך, כשפרמטר name מופיע בכל השיטות.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

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

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

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

התנהגות עדינה של API דורשת הגדרה נוספת

יש התנהגויות מסוימות של API שידרשו הגדרה נוספת של ה-API כדי לשלב אותו עם Deployment Manager. ההתנהגויות האלה כוללות:

  • ערכים שנוצרו על ידי השרת: לחלק ממשאבי ה-API יש מאפיינים שנוצרו על ידי השרת ומשתנים אחרי כל בקשה או כשאירוע מסוים מתרחש ב-API. אתם יכולים להשתמש באפשרויות מתקדמות של API כדי להגדיר ל-Deployment Manager לאחזר את הערך החדש הזה בכל פעם שמתבצעת בקשה.

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

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

  • ערכי שדות שמשתנים בכל שיטה: אם יש שיטות שמשתמשות באותו שדה אבל עם ערכים שונים, אפשר להשתמש באפשרויות של ה-API כדי לציין ל-Deployment Manager מתי להשתמש בכל ערך.

מידע נוסף מופיע במאמר בנושא הגדרת אפשרויות מתקדמות של API.

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