מפרט OpenAPI

מפרט ה-OpenAPI של Nodaro הוא תיאור קריא למכונה של ליבת ה-REST API של Nodaro, בפורמט OpenAPI 3.1, שהשרת מגיש בזמן אמת. השתמשו בו כדי ליצור לקוח עם טיפוסים ב-Go, ב-Rust, ב-Python או בכל שפה שיש לה מחולל OpenAPI, או כדי לחקור את ה-API בכל כלי שקורא OpenAPI. ל-TypeScript ול-JavaScript, ה-SDK הוא הלקוח המוכן.

הורדת המפרט

curl -s https://app.nodaro.ai/v1/openapi.json -o nodaro-openapi.json

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

מה המפרט מכסה

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

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

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

• סכמת אבטחה אחת. הסכמה bearerAuth מגדירה אסימון Bearer של HTTP, בלי bearerFormat. התיאור שלה מפרט את האסימונים שהיא מקבלת: JWT של סשן, אסימון API אישי (ndr_…), אסימון גישה של OAuth (ndr_app_…) או מפתח של אינטגרציית חיוב (ndr_bill_…). ראו את דף ה-API אימות.
• שרת יחסי. השרת של המפרט הוא /, ולכן הגדירו את כתובת הבסיס, למשל 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 רכיבים לתיאור השדות.

יצירת לקוח

# 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 שגיאות ותשאול התוצאות כמו בדף ה-API משימות.

קריאה לנקודות קצה שמחוץ למפרט

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

• כל הרכיבים משתמשים באותו נתיב. הנתיב POST /v1/{node-type}, עם ההגדרות של הרכיב כגוף הבקשה, מריץ כל רכיב, לא רק את השניים שבמפרט. את השדות של רכיב קוראים מ-GET /v1/nodes/{type}, תחת inputSchema, ומהדף שלו במדריך הרכיבים.
• כל שאר נקודות הקצה מתוארות בדפי ה-API שבתיעוד, מהדפים תהליכים והרצות ועד הדפים העלאות וקרדיטים. קראו להן עם המתודה לבקשות גולמיות של הלקוח שיצרתם, או עם כל ספריית HTTP.