The Journey From Undocumented REST API to GraphQL

REST API לא מתועד לא נשאר "רק לא מתועד". ככל שמצטברים clients, routes ולוגיקה, הוא הופך למקום שאף אחד לא רוצה לגעת בו. ספי ניניו מציג מקרה שבו מוצר web, desktop ומובייל דיברו עם אותו backend, אבל כל אחד היה צריך data אחר. הפתרון לא היה rewrite הרואי. הוא התחיל במיפוי של מה שהמערכת באמת עושה.

כשאותו API מחזיר יותר ממה שהמוצר צריך

רופא ומטופל עשויים להסתכל על אותו לוח זמנים, אבל לא צריכים אותו response. הרופא רוצה לראות פגישות, מטופלים וזמינות. המטופל רוצה רק slot פנוי. REST משותף יכול להחזיר לשניהם אותו payload, עם שדות שהצד השני לא צריך. זה לא רק עניין אסתטי. לא תמיד המשתמש נמצא על חיבור מצוין, ו-data מיותר פוגע בחוויה.

GraphQL נותן ל-client query שבו הוא בוחר את השדות. אפשר לבקש title של post ושם של author, בלי לקבל tags, likes, כתובת או כל השדות האחרים. זה גם מצמצם את רצף הבקשות מצד ה-client. GraphQL אינו קסם שמעלים את העבודה: השרת עדיין צריך לפתור קשרים ולדבר עם services. אבל הוא משנה מי מגדיר את צורת התשובה.

למה המיגרציה נתקעה

ה-backend היה Node.js בלי TypeScript, עם routes רבים, לוגיקה קיימת וסכמת Mongoose עשירה ב-refs וב-virtual values. כתיבת GraphQL schema ידנית מהתחלה לא הייתה ריאלית. גם תיעוד ידני של כל endpoint ב-Swagger דרש מאמץ עצום. מיפוי ישיר מה-database נשמע מפתה, אך מפספס את שכבת ה-API ומעביר ל-client לוגיקה שלא אמורה לזלוג אליו.

GraphQL Mesh מול Mongoose גם לא עבד היטב במבנה הזה. וזה לא היה מספיק טוב אפילו אם היה עובד: database schema לא שווה API contract. לכן ספי מחפש מקור אחר - לא הקוד התיאורטי ולא הדאטאבייס, אלא ה-requests וה-responses שהמוצר משתמש בהם בפועל.

לתעד דרך שימוש אמיתי

הטריק הוא middleware ב-Express. כשהוא פעיל, הוא שומר את res.json המקורי, עוטף אותו בפונקציית analyze, מקבל את ה-request ואת ה-response, ואז קורא למימוש המקורי. כך הוא לא רק רואה את הבקשה - הוא רואה גם את התשובה, status code, body, query params ו-path params.

QA או E2E מריצים את המוצר דרך ה-use cases שלו. הקוד מייצר Swagger/OpenAPI מתוך מה שנצפה. התוצאה חזקה דווקא בגלל מה שאין בה: endpoints שאף אחד לא משתמש בהם אינם מקבלים מקום רק כי מישהו מפחד למחוק אותם. אחר כך GraphQL Mesh מקבל את Swagger ומייצר schema. קובץ תיעוד שהיה בלתי אפשרי לכתוב ידנית הופך לקלט שנוצר מההתנהגות.

schema לא צריך לשכפל את עצמו

בדמו של translations, response של list, create ו-delete יכול להפנות לאותו type של Translation. אבל input ל-create אינו אותו type: למשל, אין לו ID. מעבר לזה, reuse אגרסיבי קושר בין input ל-response ובין mutations שונות. כשאחד משתנה, האחרים משתנים בלי שהתכוונתם. הסכמה צריכה לשקף גבולות עסקיים, לא רק לחסוך שורות.

גם GraphQL endpoint יחיד אינו אומר שהכל מגיע מאותה טבלה. resolvers יכולים להביא data ממקורות שונים ולחבר בין post ל-author. ה-client פשוט מבקש את מה שהוא צריך. זו הסיבה שהמסע מתחיל בחוזה API ותיעוד, ולא ברצון להחליף פרוטוקול.

לא פתרון לפרודקשן, כלי שמאפשר להגיע לשם

ספי מדגיש שהקוד שהציג הוא כלי מיפוי, לא middleware שרוצים להשאיר פעיל בפרודקשן. הוא נועד לפאזה מסוימת: להפעיל flag, להריץ בדיקות, לבנות baseline של ה-API ואז להחליט על תחזוקה. אפשר לעדכן schema כחלק מפיתוח פיצ'ר, או לתת ל-QA ול-CI/CD לשמור אותו עדכני.

מה לוקחים למערכת הוותיקה הבאה

הפתרון של ספי עובד כי הוא מתייחס לבדיקות לא רק כשומר סף, אלא כמקור מידע. צוות QA כבר יודע להפעיל מסכים, למלא טפסים ולבדוק תרחישים. E2E tests כבר מכירים את הנתיבים החשובים של המוצר. במקום לבקש מצוות backend לשבת מול רשימת routes אינסופית ולנחש מה חוזר מכל אחד, נותנים לשימוש האמיתי לחשוף את החוזה.

זה גם משנה את סדר העבודה. לא מתחילים בשאלה אם GraphQL הוא הדבר הכי מודרני. מתחילים בשאלות הפחות זוהרות: אילו endpoints קיימים? אילו מהם חיים? איזה status codes ותשובות הם מחזירים? אילו שדות חשופים ללקוחות, ואילו שדות קיימים רק ב-database? ברגע שיש תשובות, בחירת שכבת GraphQL היא כבר החלטה הנדסית שאפשר לבדוק, ולא אמונה בפרוטוקול.

יש כאן גם tradeoff ברור. תיעוד שנבנה מ-QA טוב רק כמו הכיסוי של QA. אם test לא מפעיל תרחיש, הוא לא יופיע ב-Swagger. לכן אין מקום להעמיד פנים שה-schema שנוצר הוא אמת מוחלטת. הוא baseline שמאפשר לצוות להתקדם, לזהות API מת, ולהתחיל לתחזק חוזה. משם אפשר להוסיף types מפורשים, לתקן שמות, להגדיר input נכון ולשים ownership על השינויים החדשים.

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

זו גם סיבה טובה להפריד בין פעולת המיפוי לבין הפעלת GraphQL מול משתמשים. קודם אפשר ליצור Swagger ולבדוק אותו מול הצוותים. אחר כך אפשר להרים playground, לנסות queries ולוודא שה-resolvers מחזירים את מה שה-client צריך. רק אחרי שהחוזה ברור עוברים את השכבה הבאה: עדכון הלקוחות ל-Apollo Client או לכל client אחר. כך לא מחליפים API ותיק ביום אחד, ולא דורשים מהפרונט להמר על schema שעוד לא נבדק.

במילים אחרות, migration טוב אינו מחיקת REST. הוא יצירת מסלול בטוח לידו: מיפוי, תיעוד, schema, אימות מול שימוש אמיתי ואימוץ הדרגתי. אם משהו חסר, יודעים איזה request צריך להריץ. אם משהו מיותר, יודעים למה אפשר להיזהר לפני שמוחקים. זה הרבה פחות דרמטי מ-rewrite, והרבה יותר שימושי לצוות שמחזיק מוצר חי.

הערך הוא לא רק GraphQL. זו דרך לפרק חוב טכני בלי לעצור הכול. מודדים התנהגות, מתעדים את מה שבאמת קיים, ורק אז בונים שכבה חדשה. להמשך על כלים ויזואליים וחוזה רכיבים, האזינו גם ל-פרק 62 על Storybook. קודם מגלים את המערכת. אחר כך משנים אותה.