> העתק ציבורי של מדריך המפתחים של ViewStream (לקריאה גם על ידי סוכני AI). רשימת המדריכים: https://www.viewstream.co.il/he/developers/guide/index.md · תיעוד ה-API: https://api.viewstream.co.il/docs/

# ניהול גרסאות ושינויים

## מה מנוהל בגרסאות כיום

| פריט | סימון הגרסה | איפה |
|---|---|---|
| ה-API לניהול | קידומת הנתיב `/v1` | כל נתיב, public.go (באנגלית) |
| מסמך OpenAPI | `info.version` (`0.2.0` בזמן הכתיבה) | api/openapi.yaml (באנגלית), מוגש כ-`/openapi.yaml` ו-`/openapi.json` |
| ה-API של Sites Delivery | קידומת הנתיב `/s/v1` וכותרת התשובה `X-VS-Sites-API: 1` | sites/types.go (באנגלית) |
| Beacons של הנגן | הנתיב `/b/v1` והשדה `v` במטען (payload) | contracts.md (באנגלית) |
| ייצוא אירועים | `schema: "vs.event.v1"` בכל אירוע | event-export.md (באנגלית) |
| Webhooks | המעטפת `{id, type, at, customer_id, data}`; `User-Agent: ViewStream-Webhooks/1` | delivery/webhook.go (באנגלית) |
| נגן | ה-loader `VSEmbed.version` (1.3.0); תצורה יכולה לנעול גרסת נגן עם `version_pin` | embed.js (באנגלית), player-configs.md (באנגלית) |

## איך מתבצעים שינויים

בפועל, כל השינויים עד היום היו **תוספתיים**: נתיבים חדשים, שדות בקשה אופציונליים חדשים, שדות חדשים
בתשובה. יומן השינויים (CHANGELOG) מסמן שינויים כאלה כ-"additive". כתבו לקוחות ש:

- מתעלמים משדות בתשובה שהם לא מכירים;
- לא תלויים בסדר השדות או בסדר המפתחות באובייקטים;
- מתייחסים למחרוזות דמויות enum (סטטוסים, סוגי אירועים, סוגי בדיקות) כקבוצות פתוחות — רשמו ללוג ודלגו על ערכים שאתם לא מכירים;
- קוראים את הרשימות המוסמכות מה-API כשיש כזו: `event_types` ב-`GET /v1/webhooks`, קטלוג הבדיקות
  ב-`GET /v1/monitors/checks`, שמות הדוחות ב-`detail` של תשובת `422` של `GET /v1/stats/export`.

שימו לב לכיוון ההפוך: **בקשות** נבדקות בקפדנות. גוף בקשה עם שדה שהנתיב לא מכיר נדחה עם `400`,
אז אל תשלחו שדות "לעתיד".

עדיין **אין מדיניות כתובה של הוצאה משימוש** (אין כותרות sunset, אין חלון תמיכה מוצהר ל-`/v1`). עד שתהיה כזו,
הניחו ששינוי שובר יגיע כקידומת נתיב חדשה, עם הודעה מראש ללקוחות ה-API.

## איפה לעקוב אחרי שינויים

- **הערות גרסה:** control-plane/docs/CHANGELOG.md (באנגלית) — כל שינוי
  ב-control-plane, מהחדש לישן.
- **תיעוד ה-API:** `https://api.viewstream.co.il/docs/` — Swagger UI מעל מסמכי ה-OpenAPI הציבוריים, שנוצרים
  מ-api/openapi.yaml (באנגלית) ומ-
  api/public-overlay.yaml (באנגלית) על ידי
  internal/apidocs (באנגלית). נתיבים פנימיים, נתיבי מפעיל ונתיבים של סשן Studio בלבד
  מוסרים מהמסמכים הציבוריים. בדיקת יחידה שומרת על התאמה בין קובץ ה-OpenAPI לנתב.