בנה והגדר כלי

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

הגדירו את הבקשה#

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

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

הגדר ומפה כניסות#

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

{
  "type": "object",
  "properties": {
    "record_id": {
      "type": "string",
      "description": "The verified identifier of the record to read"
    }
  },
  "required": ["record_id"],
  "additionalProperties": false
}

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

עצב את הפלט#

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

סקור את הגדרות ההפעלה#

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

בדוק את הדרך האמיתית#

בדוק קלט נכון, קלט לא חוקי, תוצאות ריקות, כשל בהרשאה וקריאה מוצלחת מוגבלת. אבחון בדיקה עשוי להכיל מידע רגיש של בקשה; בדוק אותם רק דרך המסלול המאושר של המנהל ותשנה לפני השיתוף. לִרְאוֹת בדיקה לפני שלקוח משתמש בכלי.