להפריד תיאור ואכיפה
קבעו גרסת מפרט שהכלים תומכים בה. תארו פרמטרים, תוכן, תשובות ודרישות אבטחה. היישום והשער עדיין צריכים לאכוף את הדרישות המוצהרות.
| רכיב | מה מתואר | בדיקה נוספת |
|---|---|---|
| סכמה | מבנה ואילוצים | אימות בפועל וכללים עסקיים. |
| תשובה מתועדת | מצב ותוכן צפויים | התאמת תשובות אמיתיות. |
| דרישת אבטחה | מנגנון וזכויות מוצהרים | בקרת גישה אמיתית לכל פעולה. |
| דוגמה | מקרה המחשה אחד | עקביות, היעדר סודות ומקרי קצה. |
סקירה לפני שיתוף
- בדקו שדות חובה, טיפוסים, טווחים, דפדוף, שגיאות ופורמטים. השתמשו בדוגמאות דמיוניות התואמות לסכמות ללא סודות או נתוני לקוחות.
- השוו את התיאור לבקשות ותשובות בסביבה מבוקרת. בדקו פרטי אימות חסרים, זכויות חסרות והפרדה בין חשבונות.
- בדקו הפניות חיצוניות והכלים שמעבדים אותן. נקו את התיאור הציבורי והגנו על סביבות ופעולות פרטיות.
תחזוקת התיעוד
בדקו הבדלים ומנו אחראי. לקוח שנוצר אוטומטית או דוגמה יכולים להיות תקינים במבנה ולפספס כלל עסקי. מסופים אינטראקטיביים דורשים סביבה מתאימה, הרשאות מוגבלות וסימון פעולות שמשנות מצב.
מקורות ראשוניים
השווה את OpenAPI לשירות הפועל.
תיאור OpenAPI שימושי כולל תגובות לכשל, סכמות ודוגמאות שלקוחות נתקלים בהן בפועל. כאשר המסמך וה-API שונים זה מזה, אינטגרציה יכולה לעבור הדגמה ולהיכשל בייצור.
- השווה מקרי הצלחה ושגיאה מול התיאור.
- תיעוד ערכים אופציונליים, עמודים ומגבלות פעולה.
- בדיקת לקוח מייצג לפני שינוי החוזה.
מקור ראשוני: IETF RFC 9457 — Problem Details for HTTP APIs. שיטה קשורה: קריאת המדריך המעשי.
ZIP ו־TAR: לחלץ בגבולות תיקייה ומשאבים
לבדוק נתיבים, קישורים ונתונים לאחר פריסה לפני פרסום הקבצים.
- חלצו לתיקייה חדשה לא ציבורית עם הרשאות מינימליות. דחו נתיבים מוחלטים, עלייה בתיקיות, קישורים וקבצים מיוחדים לא נחוצים. בדקו יעדים שנפתרו והתנגשויות לפי מערכת היעד, כולל אותיות גדולות. קידומת טקסט אינה מוכיחה תחימה.
- קבעו גבולות לכל קובץ ולמכלול על בתים שנכתבו, פריטים, עומק, זמן ומשאבי תהליך. אל תסתמכו רק על גודל דחוס או מוצהר. דחו ארכיונים מקוננים לא נחוצים או שתפו תקציב כללי. עדכנו ספרייה ומסננים.
- בדקו ../, נתיב מוחלט, קישור, כפילות וחריגת תקציב. כשל משאיר אצווה לא מפורסמת ואינו מחליף קבצים קיימים. בדקו סוגים ותוכן לפני פרסום; אמתו יעד בעת ניקוי התיקייה.
מקרה קבלה שניתן לשחזר
דוגמה בדיונית: הנתונים אינם מתארים לקוח או תוצאה שנצפתה.
הצגת נתוני המקרה
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}החלטה צפויה
דוגמה בדיונית: 2 MB דחוסים יוצרים 600 MB בתקציב 100 MB. עצרו עם חריגת הבתים שנכתבו ואל תפרסמו, גם אם הקבצים הראשונים נראים תקינים.
Python — tarfile extraction filters and further verification
האם ארכיון קטן או מסנן מבטיח בטיחות?
לא. הוא יכול לגדול מאוד. הוסיפו גבולות משאבים, כללי נתיב ובדיקת הקבצים שחולצו.
מקור ראשוני: Python — tarfile extraction filters and further verification. שיטה קשורה: קריאת המדריך המעשי.
שגיאות API: סוגים, סטטוסים וראיות
הערות המקורות המפורטות זמינות באנגלית במהדורה זו.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5