# מפרט OpenAPI

> הורידו את מפרט OpenAPI 3.1 של Nodaro מ-‎/v1/openapi.json, בדקו אילו נקודות קצה הוא מכסה וצרו לקוחות עם טיפוסים ב-Go, ב-Rust, ב-Python ועוד.

Source: https://nodaro.ai/he/docs/developers/api/openapi

**מפרט ה-OpenAPI של Nodaro** הוא תיאור קריא למכונה של ליבת ה-REST API של Nodaro, בפורמט OpenAPI 3.1, שהשרת מגיש בזמן אמת. השתמשו בו כדי ליצור לקוח עם טיפוסים ב-Go, ב-Rust, ב-Python או בכל שפה שיש לה מחולל OpenAPI, או כדי לחקור את ה-API בכל כלי שקורא OpenAPI. ל-TypeScript ול-JavaScript, ה-[SDK](https://nodaro.ai/docs/developers/sdk) הוא הלקוח המוכן.

## הורדת המפרט
```bash
curl -s https://app.nodaro.ai/v1/openapi.json -o nodaro-openapi.json
```

המפרט ציבורי, ולכן לא צריך אסימון, והוא נשמר במטמון למשך 5 דקות. התקנה באירוח עצמי מגישה מפרט משלה באותו נתיב, `/v1/openapi.json`. גם הדף **מפתחות API** ב**הגדרות** מקשר אליו.

## מה המפרט מכסה
המפרט הוא **חלק שנבחר בקפידה** מה-API: הוא מתאר את ליבת האוטומציה, לא כל נתיב. הוא מכסה:

| תחום | נתיבים |
| --- | --- |
| תהליכים | `GET /v1/projects/{projectId}/workflows`, `POST /v1/workflows/{id}/run`, `POST /v1/workflows/{id}/move` |
| משימות | `GET /v1/jobs/{id}`, `GET /v1/jobs/{id}/status` |
| גילוי רכיבים | `GET /v1/nodes`, `GET /v1/nodes/{type}` |
| יצירה | `POST /v1/generate-image`, `POST /v1/generate-video` |
| OAuth | `POST /v1/oauth/token`, `GET /v1/oauth/app-info` ונתיבי החיבור של תוספים תחת `/v1/oauth/plugin/` |
| קרדיטים | `POST /v1/credits/model-costs`, `POST /v1/credits/video-pro-estimate` |

המפרט מגדיר ארבע סכמות משותפות: `WorkflowSummary`, `Job`, `JobStatus` ו-`NodeDescriptor`. השרת בונה את המפרט מהגדרות הנתיבים שלו עצמו, ולכן את הרשימה המדויקת תמצאו בקובץ שהשרת מגיש.

כמה דברים שכדאי לדעת כשמשתמשים בו:

- **סכמת אבטחה אחת.** הסכמה `bearerAuth` מגדירה אסימון Bearer של HTTP, בלי `bearerFormat`. התיאור שלה מפרט את האסימונים שהיא מקבלת: JWT של סשן, אסימון API אישי (`ndr_…`), אסימון גישה של OAuth (`ndr_app_…`) או מפתח של אינטגרציית חיוב (`ndr_bill_…`). ראו את דף ה-API [אימות](https://nodaro.ai/docs/developers/api/authentication).
- **שרת יחסי.** השרת של המפרט הוא `/`, ולכן הגדירו את כתובת הבסיס, למשל `https://app.nodaro.ai`, כשאתם יוצרים את הלקוח.
- **פעולות ציבוריות.** כל פעולה דורשת `bearerAuth`, חוץ מתשע פעולות שמסומנות `security: []` ולא מקבלות אסימון: `GET /v1/nodes`, `GET /v1/nodes/{type}`, `POST /v1/oauth/token`, `GET /v1/oauth/app-info`, ארבעת נתיבי החיבור של תוספים תחת `/v1/oauth/plugin/` ו-`POST /v1/credits/model-costs`.
- **שדות היצירה.** הנתיבים `POST /v1/generate-image` ו-`POST /v1/generate-video` מפרטים את גוף הבקשה המלא שלהם, כולל `connectedReferences`, `direction` ו-`subject`. ראו את דף ה-API [רכיבים](https://nodaro.ai/docs/developers/api/nodes) לתיאור השדות.

## יצירת לקוח
```bash
# Go
oapi-codegen -generate types,client -package nodaro https://app.nodaro.ai/v1/openapi.json

# Rust
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g rust -o nodaro-rs

# Python
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g python -o nodaro-py
```

אחר כך כוונו את הלקוח לכתובת הבסיס שלכם, ושלחו `Authorization: Bearer <token>` עם כל בקשה, חוץ מהפעולות הציבוריות. כל השאר עובד כמו שמתואר בדפים האחרים: גוף בקשה ותגובה ב-JSON, מעטפת השגיאה `{ "error": { "code", "message" } }` מדף ה-API [שגיאות](https://nodaro.ai/docs/developers/api/errors) ותשאול התוצאות כמו בדף ה-API [משימות](https://nodaro.ai/docs/developers/api/jobs).

## קריאה לנקודות קצה שמחוץ למפרט
ה-REST API עובד מכל שפה, גם במקומות שהמפרט לא מתאר: שולחים אסימון Bearer ו-JSON, ומקבלים JSON בחזרה.

- **כל הרכיבים משתמשים באותו נתיב.** הנתיב `POST /v1/{node-type}`, עם ההגדרות של הרכיב כגוף הבקשה, מריץ כל רכיב, לא רק את השניים שבמפרט. את השדות של רכיב קוראים מ-`GET /v1/nodes/{type}`, תחת `inputSchema`, ומהדף שלו ב[מדריך הרכיבים](https://nodaro.ai/docs/nodes).
- **כל שאר נקודות הקצה מתוארות בדפי ה-API שבתיעוד**, מהדפים [תהליכים](https://nodaro.ai/docs/developers/api/workflows) ו[הרצות](https://nodaro.ai/docs/developers/api/executions) ועד הדפים [העלאות](https://nodaro.ai/docs/developers/api/uploads) ו[קרדיטים](https://nodaro.ai/docs/developers/api/credits). קראו להן עם המתודה לבקשות גולמיות של הלקוח שיצרתם, או עם כל ספריית HTTP.

## שאלות נפוצות

### איפה נמצא מפרט ה-OpenAPI של Nodaro?

ב-Nodaro Cloud, מפרט ה-OpenAPI נמצא בכתובת https://app.nodaro.ai/v1/openapi.json. המפרט ציבורי, ולכן לא צריך אסימון, והתקנה באירוח עצמי מגישה מפרט משלה באותו נתיב.

### האם מפרט ה-OpenAPI מכסה כל נקודת קצה של Nodaro?

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

### איך קוראים לרכיב שלא נמצא במפרט?

כל הרכיבים משתמשים באותו נתיב: POST /v1/‎ ואחריו סוג הרכיב, עם ההגדרות של הרכיב כגוף הבקשה. קבלו את השדות של הרכיב מ-GET /v1/nodes/:type, ואז שלחו את הבקשה עם המתודה לבקשות גולמיות של הלקוח שיצרתם, או עם כל ספריית HTTP.

### איזה אימות המפרט מגדיר?

מפרט ה-OpenAPI מגדיר סכמה אחת, bearerAuth: אסימון Bearer של HTTP בלי פורמט קבוע. הסכמה מקבלת JWT של סשן, אסימון API אישי, אסימון גישה של OAuth או מפתח של אינטגרציית חיוב. תשע פעולות ציבוריות, כגון GET /v1/nodes, מסומנות security: []‎ ולא מקבלות אסימון.