הגדירו את פעולת ה-VPN לפני השוואת API-ים
בקרת חיבורים, אספקת פרופילים, ניהול משתמשים ותצפית הם API-ים שונים. תנו שם לאובייקט, לפעולה ולתנאי ההצלחה קודם.
דף מוצר מצהיר שיש API, ופגישת האינטגרציה נתקעת בשאלה השנייה. איזו פעולה, על איזה אובייקט, מי קורא לה, ומה נחשב להצלחה? מענה על ארבע השאלות האלה לפני השוואת מוצרים בדרך כלל מסלק חצי מהמועמדים. הוא גם הופך את ההשוואה שנותרה למשהו שבדיקה יכולה להכריע.
החליפו את הטענה שיש API בפעולה אחת
API הוא אמצעי תעבורה, לא יכולת. נקודת קצה של REST, סוקט מקומי ועטיפת שורת פקודה יכולים כולם להיקרא API, והם אינם מציעים פעולות שקולות.
כתבו את הפעולה כמשפט לפני שאתם פותחים את התיעוד.
התחלת חיבור מקומי היא פעולה בצד הלקוח שמולה עומד משתמש. הנפקת פרופיל מכשיר היא פעולת אספקה שמאחוריה מלאי. השבתת הגישה של משתמש היא פעולה מנהלית שיש לה עקבות ביקורת. שלוש אלה חיות בדרך כלל ברכיבים שונים, בבעלות צוותים שונים, בסמכות שונה.
ארבעה שדות שהופכים את החוזה לבדיק
מלאו ארבעה שדות לכל פעולה: האובייקט, הפעולה, הקורא ותנאי ההצלחה. חוזה שחסר בו שדה הוא משאלה.
הטבלה היא כל גיליון העבודה:
| Field | Question | Example |
|---|---|---|
| Object | What is being acted on? | One enrolled device |
| Action | Observe, create, change, start, stop, or revoke? | Revoke |
| Caller | Which identity calls it? | Deployment service |
| Success | What observable state proves it? | Future sign-in denied |
תנאי ההצלחה הוא השדה שאנשים מדלגים עליו, והוא זה שמכריע אם האינטגרציה עובדת. הגדרה שנשמרה אינה מנהרה פעילה, וחשבון שהושבת אינו הפעלה שהסתיימה.
אם שתי פעולות זקוקות לקוראים שונים, אלה שתי אינטגרציות. איחודן בחשבון שירות אחד משמעו בדרך כלל מתן סמכות רבה מזו שכל אחת מהן צריכה.
התאימו את הממשק לשכבה האמיתית שלו
ממשק הניהול הקהילתי של OpenVPN מדבר עם דמון דרך TCP או סוקט Unix. פקודותיו כוללות תצפית במצב ואותות לדמון.
זה הופך אותו לערוץ בקרה של הדמון, לא ל-API של מנוי מתארח ולא לשירות רישום משתמשים. קריאה זהירה בתיעוד שלו מונעת בנייה מול שכבה שאינה הבעלים של האובייקט.
אותו תיעוד אומר גם שהפרוטוקול אינו נושא הצפנה משל עצמו. מי שמגיע לסוקט יכול לשלוט בדמון, ולכן התייחסו אליו כאל בקרה רגישה ולא כאל זרם מדדים. קשרו אותו ל-loopback או לסוקט Unix, והציבו אותו מאחורי הסדר מוגבל אם קורא מרוחק זקוק לו. חשיפה לאינטרנט מטעמי נוחות הופכת ערוץ בקרה לתקרית.
פרטו את ההתנהגות לאחר הקריאה
קבלה אינה זהה להשלמה. הדמון עשוי לחזור לפני שהמנהרה עולה, לכן המתינו לאירוע ההשלמה או הכשל המתועד וקשרו אותו לבקשה ששלחתם.
החליטו מה עושה הקורא אם התגובה אבדה. חזרה עיוורת על יצירה או על התחברות מחדש אינה זהה לבדיקה אם הבקשה הראשונה כבר השפיעה.
הסרת גישה היא לפחות שלוש פעולות שונות: חסימת כניסה עתידית, סיום הפעלה חיה ושלילת אישור הגישה. בקשו את אלה שהמדיניות באמת דורשת, ואמרו בחוזה איזו היא איזו. אל תסמנו עדכון חשבון מוצלח אחד כשלילה מלאה בלי ראיה. ההבדל חשוב בזמן תקרית, כשהשעון דולק.
בדקו את החוזה עם פיילוט
פיילוט קטן ומאושר צריך לכסות הצלחה, דחייה, הפרעה וניסיון חוזר, ואחריהם פעולת היישום שאמורה להיות מותרת או אסורה.
עבור ממשק ברמת הדמון, שתי פקודות מתרגלות תצפית ואות:
echo state | nc -w 2 127.0.0.1 7505
echo signal SIGTERM | nc -w 2 127.0.0.1 7505העניקו רק את הסמכות שהפעולה דורשת. הרחיקו סודות מיומני שגרה, ותעדו מספיק פרטים פרטיים כדי לומר איזה יעד נפגע ואיך זה הסתיים.
כתבו את מסלול השחזור למקרה שה-API לבקרה עצמו אינו זמין. בחרו את הממשק שהוא הבעלים של האובייקט ושל מחזור חייו; הצהרות אוטומציה בדף מוצר אינן תחליף.