כל נקודת קצה יושבת תחת `/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
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](https://www.rfc-editor.org/rfc/rfc9745)). בדוגמה שלמעלה, `@1735689600` הוא `2025-01-01T00:00:00Z`.
- `Sunset` — התאריך המוקדם ביותר שבו הפעולה עשויה להיות מוסרת, בפורמט IMF-fixdate ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), תמיד לפחות 180 יום אחרי `Deprecation`.
- `Link` — מפנה חזרה לטבלת ההוצאות משימוש שבעמוד הזה, כך שגם לקוח שרק רושם כותרות ליומן עדיין יכול לגלות למה.

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

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

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

> **פעולות שהוצאו משימוש כרגע**
>
> אין. אף פעולה בממשק הנוכחי לא הוצאה משימוש.

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

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

| תאריך | שינוי |
| --- | --- |
| 2026-09-07 | תיקון תיעודי, לא שינוי שובר: `nextCursor` פורסם במסמך ה-OpenAPI כ-`string[]`; פורמט התקשורת בפועל תמיד היה `string \| null`. המסמך תואם עכשיו למה שהממשק שלח מאז ומתמיד — אף לקוח שקרא את `nextCursor` כמחרוזת שיכולה להיות `null` לא טעה מעולם. |