ה-API של monday.com: מה שבאמת מגביל אותך זה מורכבות, לא מספר קריאות

ל-monday.com יש API אחד בלבד, והוא GraphQL. אין REST, אין נקודות קצה לכל משאב - הכול הוא בקשת POST אחת לאותה כתובת, וההבדל בין בקשות הוא בשאילתה עצמה. זה משחרר מאוד, אבל זה גם מעביר את כל האחריות על היעילות אליך, וכאן רוב האינטגרציות נכשלות.

הבסיס

נקודת הקצה היחידה היא https://api.monday.com/v2, וכל בקשה היא POST עם שלוש כותרות חובה:

• Authorization - טוקן ה-API שלך
• Content-Type: application/json
• API-Version - גרסה מתוארכת, למשל 2023-07

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

מה שבאמת מגביל: תקציב המורכבות

זו הנקודה החשובה ביותר במאמר. יש שתי מגבלות שונות לחלוטין, ורוב האנשים שמים לב רק לזו הלא נכונה.

מגבלת קריאות יומית

תקציב מורכבות - האילוץ האמיתי

לכל שאילתה מחושב ניקוד מורכבות, והתקציב הוא נקודות לדקה: כמיליון נקודות בחשבונות חינמיים וניסיון, ובין 5 ל-10 מיליון בהתאם לסוג הטוקן. החלון נע ומתאפס 60 שניות אחרי הקריאה הראשונה. חריגה מחזירה ComplexityException.

ההבדל המעשי: אתה יכול להיחסם אחרי קריאה אחת. שאילתה שמבקשת את כל הלוחות, ובכל לוח את כל הפריטים, ובכל פריט את כל ערכי העמודות ואת כל העדכונים - היא מכפלה, והמכפלה הזו יכולה לבלוע מיליוני נקודות בבת אחת. מגבלת ה-1,000 קריאות ביום נשארת רחוקה, והאינטגרציה בכל זאת מתה.

איך מודדים במקום לנחש

אפשר להוסיף לשאילתה את שדה complexity, והתשובה תכלול את עלות השאילתה, את התקציב שנותר לפני ואחרי, ואת מועד האיפוס. זה הכלי המרכזי לתכנון קיבולת. להריץ את השאילתה על לוח קטן, לקרוא את המספר, ולהכפיל בגודל הצפוי - זה ההבדל בין אינטגרציה שמחזיקה ובין כזו שנופלת ביום שהלקוח מוסיף עוד 5,000 פריטים.

יש גם מגבלת מקביליות, שמפורסמת בכותרת RateLimit-Policy בתשובה. יש לקרוא אותה מהתשובה במקום להניח מספר.

המלכודת שתופסת ביום הראשון: column_values

ב-monday, ערכי העמודות של פריט אינם שדות רגילים. הם חוזרים כ-JSON שמקודד בתוך מחרוזת, ולכל סוג עמודה יש מבנה משלו - עמודת סטטוס, עמודת תאריך ועמודת אנשים נראות שונה לגמרי.

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

שתי הנחיות מעשיות:

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

עוד ארבע נקודות ששוות זמן

• GraphQL מחזיר 200 גם על שגיאה. זו התנהגות סטנדרטית של GraphQL, לא של monday: הסטטוס הוא 200 והשגיאה נמצאת במערך errors בגוף התשובה. קוד שבודק רק את קוד הסטטוס יחשוב שהכול הצליח. יש לבדוק את הגוף תמיד.
• עימוד. אין להסתמך על שליפה של הכול בבת אחת. עבודה בעמודים היא גם החובה התפעולית וגם הדרך הישירה להוריד מורכבות.
• לבקש רק שדות שצריך. זו כל הנקודה של GraphQL, וב-monday זה גם מה שקובע כמה נקודות מורכבות תשלם. שאילתה שמבקשת שלושה שדות זולה בהרבה מאחת שמבקשת עשרים.
• Webhooks במקום תשאול. monday מאפשרת webhooks, ובכל תרחיש של "כשמשהו משתנה" הם עדיפים על תשאול מחזורי - הן מבחינת מורכבות והן מבחינת עדכניות.

מתי monday מספיקה ומתי לא

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

בפרויקטים שבהם הנפח גדל, הדפוס שמחזיק הוא לסנכרן את מה שצריך למסד נתונים משלך ולהריץ את הדוחות שם, ולהשאיר את monday כממשק העבודה של הצוות. זו גם השאלה הרחבה יותר של מתי מערכת מדף מספיקה ומתי צריך CRM ייעודי.