גרסאות והוצאה משימוש

כל נקודת קצה יושבת תחת /api/v1. העמוד הזה הוא כל המדיניות: מה /api/v1 מבטיח לעולם לא לעשות, מה נחשב שינוי שובר, איך מוציאים פעולה אחת משימוש בלי לשבור אף אחד שעדיין קורא לה, ויומן כל התיקונים ברמת החוזה שביצענו אי פעם.

יציבות /api/v1#

בתוך /api/v1 אנחנו מבצעים אך ורק שינויים תוספתיים:

• נקודת קצה חדשה.
• שדה בקשה אופציונלי חדש.
• שדה תשובה חדש.
• code שגיאה חדש ונפרד עבור מצב כשל חדש באמת.

לעולם לא נעשה, בתוך /api/v1:

• נסיר שדה מתשובה.
• נצמצם את הטיפוס של שדה (למשל, שדה שיכול להיות null והופך לכזה שלעולם אינו null — זה בסדר; ההפך — או הרחבת string ל-string | number — לא).
• נוסיף שדה בקשה שהוא חובה.
• נשנה את קוד סטטוס ה-HTTP שפעולה מחזירה עבור תוצאה נתונה.
• נשנה איזה error.code מוחזר עבור מצב כשל קיים.

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

מה נחשב שינוי שובר#

כל דבר ברשימת ה“לעולם לא” שלמעלה הוא שינוי שובר, והוא לעולם לא נוחת בתוך /api/v1. שינוי שובר משמעו /api/v2, שיוכרז לפחות 180 יום לפני ש-/api/v1 מתחיל בהוצאה משימוש משלו. שתי הגרסאות רצות זו לצד זו לאורך כל תקופת ההודעה — שום דבר לא נשמט מתחת לרגליו של מי שמתממשק, בלי התראה.

הוצאת פעולה משימוש#

אפשר להוציא פעולה בודדת משימוש בתוך /api/v1 — היא עדיין מתפקדת במלואה, אך מסומנת להסרה עתידית (בדרך כלל משום ש-/api/v2 או פעולה חדשה יותר מחליפה אותה). לאורך כל שארית חייה היא נושאת שלוש כותרות ואת "deprecated": true במסמך ה-OpenAPI:

HTTP/1.1 200 OK
Deprecation: @1735689600
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://docs.institflow.com/en/guides/versioning#deprecations>; rel="deprecation"

• Deprecation — מתי החלה ההוצאה משימוש, בצורת @ ואחריו שניות Unix (RFC 9745). בדוגמה שלמעלה, @1735689600 הוא 2025-01-01T00:00:00Z.
• Sunset — התאריך המוקדם ביותר שבו הפעולה עשויה להיות מוסרת, בפורמט IMF-fixdate (RFC 8594), תמיד לפחות 180 יום אחרי Deprecation.
• Link — מפנה חזרה לטבלת ההוצאות משימוש שבעמוד הזה, כך שגם לקוח שרק רושם כותרות ליומן עדיין יכול לגלות למה.

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

כותרות מגבלת הקצב#

כל תשובה — מוצאת משימוש או לא, מוצלחת או לא — נושאת RateLimit-Limit, RateLimit-Remaining ו-RateLimit-Reset. כל תשובת 429 RATE_LIMITED — בין אם מהמגביל הכללי לפי IP/משתמש ששומר על כל מסלול, ובין אם מהתקציב הייעודי של מפתח API סודי — נושאת בנוסף Retry-After, בשניות, כך שלקוח מנומס תמיד יודע בדיוק כמה להמתין בלי לנחש מתוך RateLimit-Reset לבדה.

יומן שינויים#

תיקונים ברמת החוזה והוצאות משימוש, החדשים ביותר קודם.