REST API עם RemObjects SDK: ניהול גרסאות וניפוי שגיאות של נקודות קצה JSON באופן מסודר (Delphi קטעי מקור)

מדוע „REST API עם RemObjects SDK“ בפועל פעמים רבות מחליטה בשולי המערכת

API של REST עם RemObjects SDK נדיר שנמדד על־פי שירות „Hello World“; ההכרעה נעשית בנקודות שבהן הפעלה, legacy ואינטגרציה מתנגשים: ניהול גרסאות ללא השבתה, התנהגות שגיאות קונסיסטנטית בכל נקודות הקצה, יכולת דיבאג רפרודוצבילי בשרשראות פרוקסי והיכולת לקשר בקשות במדויק בעת בעיה.

RemObjects SDK מספקת לכך תשתית נרחבת: שירותים, פורמטי הודעות, סריאליזציה, אירוח (למשל כWindows- ו Linux-Services או מאחורי IIS/Reverse Proxy) ונקודות מובנות לטיפול מרכזי בשגיאות. במה שנבנה בהדרגה בנוף של תוכנות עסקיות לעיתים חסר הוא חוזה שמנוהל בעקביות: אילו שדות JSON יציבים? כיצד נסמן שגיאות? כיצד נזהה בקשה לאחר שעברה דרך Load Balancer, TLS-Termination ורבדי Backend?

הגישה הבאה (כולל קטעי Delphi) מציגה קו עמיד ל־RemObjects SDK: לגרסון חוזי JSON, לאכוף Correlation-ID (מזהה בקשה למעקב), לתרגם Exceptions לסטטוס HTTP ולאובייקטי שגיאה ב‑JSON ובמקביל לא לערב דיבאגינג ותפעול זה נגד זה. בנוסף נתבונן במקרי קצה שמופיעים בסביבות אמתיות לעתים תכופות: תזמון שרת (threading), גישות מסד נתונים במסגרת החלפת BDE עם חיבור טבעי, כותרות פרוקסי, тайм־אאוטים ו‑payloads „מלוכלכים“ מצד הלקוח.

החלטת ארכיטקטורה: גרסאות באמצעות סוג מדיה במקום URL

רבות מה‑APIs מגרסאות דרך נתיבים כמו /v1/. זה פרגמטי, אבל באינטגרציות ארוכות טווח (למשל חיבורי ERP/DMS/CRM) זה מוביל לעתים לכפילויות בכתובות URL, נתיבים כפולים, בדיקות כפולות ושאלות מסוג „איזו גרסה אנחנו בעצם משתמשים?“ בתיעוד תפעולי.

אלטרנטיבה היא גרסון דרך ה־Media Type (Content Negotiation). הלקוח שולח למשל Accept: application/vnd.company.order+json;v=2. השרת קורא את הגרסה באופן דטרמיניסטי ומתאים את ההתנהגות של החוזה/DTO בהתאם. זה עובד בשרשראות פרוקסי ו‑cache אם ההדרים מועברים בצורה נקייה. בנוסף, למנהלים זה נוח לבדיקה: בקשה ניתנת לשחזור בעזרת Curl/Postman מבלי שה‑URLs ישתנו.

RemObjects SDK אינה „טהורה ביחס לREST“, אלא מסגרת שירות פרגמטית. לכן הגישה של סוג מדיה משתלמת: אתם שומרים על נקודות קצה יציבות ועדיין מפתחים חוזים. החשוב הוא שתמיד תערכו את קריאת הגרסה בצורה מרכזית, תחליטו במקום אחד ותעבירו את התוצאה להקשר השירות שלכם.

מתי משתבש שימוש בכותרת Accept?

בפועל יש שלוש נקודות שבירה טיפוסיות שכדאי לטפל בהן מראש:

• מדיניות פרוקסי: חלק מה‑Reverse Proxies/כללי WAF מנרמלים או מסננים את כותרת ה‑Accept. במקרה כזה ה‑API שלכם יחזור בשתיקה לברירת המחדל. פתרון: בדקו במפורש את כללי הפרוקסי; במידת הצורך הסתמכו על X-Api-Version כגיבוי.
• ספריות לקוח: חלק מלקוחות HTTP מגדירות כותרות Accept משלהן ומחליפות ערכים. פתרון: תמכו בגרסת חוזה גם כפרמטר שאילתה אופציונלי (כרק גיבוי), או פרסו את כותרת ה‑Accept בצד השרת בסובלנות גבוהה.
• Caching: כאשר מופעל Response-Caching, על ה‑Cache להשתנות בהתאם ל־Accept (Vary: Accept), אחרת הוא יחזיר גרסה 1 ללקוחות בגרסה 2. פתרון: להגדיר במודע את Vary, או לבטל Caching ברמת ה‑API.

קטע מקור: Request-Context, Correlation-ID, גרסה ומיפוי שגיאות

הקוד נערך בכוונה כך שהוא ישתלב בפרויקטי שרת קיימים של RemObjects: שכבת Context קטנה, מפענח לגרסת ה‑API (מה־Accept), מנגנון Correlation‑ID ומיפוי Exceptions מרכזי. מונחים:

• Correlation-ID: מזהה ייחודי לכל בקשה, שמוחזר בתשובה ומשמש להתייחסות בלוגים.
• Exception-Mapping: המרת חריגים פנימיים של Delphi לאובייקטי שגיאה יציבים הניתנים לעיבוד בצד הלקוח (כולל סטטוס HTTP).
• Contract-Version: גרסת חוזה ה‑JSON שקובעת את ההתנהגות והשדות.

unit Api.Infrastructure;

interface

uses
  System.SysUtils, System.Classes, System.StrUtils, System.Generics.Collections,
  System.JSON;

type
  EApiError = class(Exception)
  private
    FHttpStatus: Integer;
    FCode: string;
    FCorrelationId: string;
  public
    constructor Create(const AHttpStatus: Integer; const ACode, AMessage, ACorrelationId: string);
    property HttpStatus: Integer read FHttpStatus;
    property Code: string read FCode;
    property CorrelationId: string read FCorrelationId;
  end;

  TApiContext = record
    CorrelationId: string;
    ContractVersion: Integer;
    RemoteIp: string;
    UserAgent: string;
    class function New: TApiContext; static;
  end;

  TApiVersion = record
    class function FromAcceptHeader(const AAccept: string; const ADefault: Integer = 1): Integer; static;
  end;

  TApiErrorMapper = class
  public
    class function ToErrorJson(const E: Exception; const ACorrId: string): TJSONObject; static;
    class function ToHttpStatus(const E: Exception): Integer; static;
    class function SafeMessage(const E: Exception): string; static;
  end;

implementation

{ EApiError }

constructor EApiError.Create(const AHttpStatus: Integer; const ACode, AMessage, ACorrelationId: string);
begin
  inherited Create(AMessage);
  FHttpStatus := AHttpStatus;
  FCode := ACode;
  FCorrelationId := ACorrelationId;
end;

{ TApiContext }

class function TApiContext.New: TApiContext;
begin
  Result.CorrelationId := '';
  Result.ContractVersion := 1;
  Result.RemoteIp := '';
  Result.UserAgent := '';
end;

{ TApiVersion }

class function TApiVersion.FromAcceptHeader(const AAccept: string; const ADefault: Integer): Integer;
// Erwartet z.B.: application/vnd.company.order+json;v=2
var
  Parts: TArray<string>;
  P: string;
  V: string;
  I: Integer;
begin
  Result := ADefault;
  if AAccept.Trim.IsEmpty then
    Exit;

  Parts := AAccept.Split([';', ',']);
  for P in Parts do
  begin
    V := Trim(P);
    if StartsText('v=', V) then
    begin
      if TryStrToInt(Copy(V, 3, MaxInt), I) and (I > 0) and (I < 100) then
        Exit(I);
    end;
  end;
end;

{ TApiErrorMapper }

class function TApiErrorMapper.SafeMessage(const E: Exception): string;
// Im Betrieb keine internen Details, keine SQL, keine Pfade.
// Für Debug/Stage kann man das über Konfiguration erweitern.
begin
  if E is EApiError then
    Exit(E.Message);

  if E is EArgumentException then
    Exit('Ungültige Parameter.');

  Exit('Interner Fehler.');
end;

class function TApiErrorMapper.ToHttpStatus(const E: Exception): Integer;
begin
  if E is EApiError then
    Exit(EApiError(E).HttpStatus);

  if E is EArgumentException then
    Exit(400);

  Exit(500);
end;

class function TApiErrorMapper.ToErrorJson(const E: Exception; const ACorrId: string): TJSONObject;
var
  Code: string;
  Status: Integer;
  Msg: string;
begin
  Status := ToHttpStatus(E);
  Msg := SafeMessage(E);

  if E is EApiError then
    Code := EApiError(E).Code
  else if E is EArgumentException then
    Code := 'bad_request'
  else
    Code := 'internal_error';

  Result := TJSONObject.Create;
  Result.AddPair('error', TJSONObject.Create
    .AddPair('code', Code)
    .AddPair('message', Msg)
    .AddPair('httpStatus', TJSONNumber.Create(Status))
    .AddPair('correlationId', ACorrId));
end;

end.

מטרה: הקשר בקשה יציב במקום „באיזה מקום ב־ThreadLocal”

קטע הקוד מפריד בכוונה: TApiContext הוא המצב המינימלי שתרצו להעביר. ב־RemObjects SDK הרבה רץ דרך הקשר Server-/Channel. בפרויקטים הטרוגניים (למשל Worker‑Threads נוספים, DB‑Queue, עבודות רקע) העברת הקשר במפורש לעיתים עמידה יותר מאשר Threadlocals נסתרות, כיוון שהיא עושה את תחרותיות והמעברים בהקשר לגלויים יותר.

מגבלות: גרסת ה‑Accept‑Header מניחה שה‑Reverse Proxy שלכם (nginx, IIS ARR, Traefik) מעביר את ההדר ללא שינוי. בסביבות מסוימות מסננים או מקבצים Accept‑Headers „לא שגרתיים“.

מכשולים: גרסאות דרך Accept טובות רק כמו מערכת הבדיקות שלכם. אם לקוחות משתמשים בספריות ששוכבות על ה‑Accept או משנותו, ה‑API עלול לפתע לחזור לברירת המחדל. ללקוחות Legacy כדאי לספק ברירת מחדל, אך יש להופיעה במערכת הניטור (למשל אזהרת לוג „Version defaulted“).

אפשרויות: אם אתם מעדיפים לבצע גרסאות דרך X-Api-Version: ה‑Parser זהה, רק המקור הוא Header אחר. מנקודת מבט של Gateways זה לעיתים קל יותר לשלוט בו.

אינטגרציה ב‑RemObjects SDK: Correlation‑ID ומיפוי חריגים בכניסה לשירות

האימפקט האמיתי נוצר כאשר מוחלים את המנגנון בעקביות בקצוות השרת: פעם אחת בכניסת ה‑Request לקרוא מה‑Headerים, ופעם אחת ביציאת ה‑Exception לתרגום לתשובת Response יציבה. בהתאם ל־Hosting (למשל RO‑HTTP‑Server, IIS‑Hosting, עצמו מופעל Windows-/Windows- ו‑Linux‑Services) נקודות ה‑Hook הקונקרטיות שונות; העיקרון נשאר זהה: לבנות Context, להפעיל את הלוגיקה העסקית, למפות חריגים באופן מרכזי.

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

מהלך מעשי (קצר וממוקד ביישום)

1. לקרוא את ה‑Correlation‑ID מתוך Request‑Header X-Correlation-ID; אם חסר — ליצור בצד השרת (למשל GUID).
2. לקרוא את גרסת החוזה מתוך Accept (או מתוך X-Api-Version).
3. לוג תחילת הבקשה: מתודה, נתיב, Correlation‑ID, IP מרוחק, ולהתחיל מדידת משך.
4. להריץ את הלוגיקה העסקית; לעטוף קריאות ל‑DB בטרנזקציות ככל שניתן.
5. לתפוס חריגות: לקבוע HTTP‑Status, ליצור אובייקט שגיאה JSON, להגדיר Response‑Header X-Correlation-ID.
6. לוג סוף הבקשה: סטטוס, משך, במידת הצורך קוד שגיאה.

ריבוי תהליכים בשרת: מדוע Correlation‑ID ללא משמעת הקשר הופכת לחסרת ערך

מקרה גבול נפוץ של Delphi: מתודת השירות מפעילה עבודה אסינכרונית (למשל יצירת דוחות, ייבוא, דחיפה ל‑DMS). אז ה‑Request‑Thread המקורי כבר אינו זה שכותב שורות לוג מאוחר יותר. אם ה‑Correlation‑ID ידועה רק „בהתחלה“, היכולת למעקב מתפרקת.

כלל פרגמטי: כל מה שלא נשאר בצורה מוחלטת ב‑Request‑Thread צריך לקבל את ה‑Context מועבר במפורש. גם אם זה ייראה כרשימות פרמטרים ארוכות — זה משתלם. לחלופין ניתן לעבוד עם אובייקט Context מוגדר היטב שמועבר במכוון ל‑Worker (במקום משתני גלובל או סינגלטונים נסתרים).

נקודות שבר טיפוסיות בשרתי RemObjects/Delphi:

• חיבורים ל-DB לכל Thread: BDE-Ablosung mit nativer Anbindung-Verbindungen אינם משתפים באופן בטוח ל־Threads באופן אוטומטי. Connection-Pool או חיבור נפרד לכל Thread הם לעתים קרובות יותר הגיוניים מאשר „חיבור גלובלי“.
• גבולות טרנזקציה: אם בתוך Request יש לכם כמה שלבים ששייכים יחד, הטרנזקציה חייבת להישאר באותה יחידה לוגית. עבודה אסינכרונית לא צריכה להמשיך „בשגגה“ באותה טרנזקציה.
• ביטול: אם הלקוח מבטל (Proxy timeout, Browser closed), השרת לעתים קרובות ממשיך לפעול. שקלו במודע האם עבודת רקע עדיין הגיונית במצב כזה.

גישה לנתונים וקודי שגיאה: 409 אינו „גם 500“

בפרויקטים של אינטגרציה מיפוי שגיאות מדויק הוא יותר מאסתטיקה. הוא קובע האם הצד שמולכם (ERP-Connector, ETL-Job, פורטל לקוחות) יכול להגיב כראוי. כמה קווים מנחים מעשיים שהוכחו בסביבות Delphi/RemObjects:

• 400 Bad Request: אימות, פרמטרים חסרים/שגויים, JSON שלא ניתן לנתח. חשוב: התגובה צריכה להישאר יציבה גם אם ה־Body פגום.
• 401/403: הפרידו בין אימות לבין הרשאה. 401 משמעותו „אין זהות/זהות לא תקינה“, 403 „הזהות תקינה, אך אסור“.
• 404: המשאב לא קיים. היזהרו מנקודת מבט אבטחה: לא תמיד יש לגלות אם משהו קיים.
• 409 Conflict: קונפליקט תפעולי/עסקי (למשל קונפליקט גרסאות, „הסטטוס אינו מאפשר פעולה זו“, הפרת מפתח ייחודי כשהיא רלוונטית מבחינה עסקית).
• 422 Unprocessable Content: כאשר תחבירית הכל תקין אך אימות עסקי נכשל (לא כל צוות משתמש ב-422, אך לעתים הוא ברור יותר מ-400).
• 500: כל מה שאינכם מצליחים לסווג בצורה נקייה. זה כולל גם „DB down“, „Timeout“, „Unhandled Exception“.

טריק ספציפי ל־Delphi: שגיאות DB רבות מתעוררות כ־Exceptions גנריות. משתלם בשכבת גישת הנתונים לזהות מצבים מוכרים ולהמירם ל־EApiError. חשוב: אל תכלילו קטעי SQL או שמות טבלאות/עמודות פנימיים בהודעת הלקוח. פרטים אלה שייכים ללוג, לא לתגובה.

טריק דיבוג: שגיאות שניתנות לשחזור באמצעות „Contract Snapshot“

מפתיע, אבל בהפעלה מאוד מועיל: שמרו בעת שגיאות (או באופן ממוקד עבור Correlation-IDs מסוימות) „Snapshot“ של Request-Headern + Request-Body בקובץ Debug-Spool. זה אינו רישום מתמשך (פרטיות/נפח), אלא כלי מבוקר לשחזור מקרים שקשה לשחזר בסמיכות לייצור.

חשוב: Snapshot אסור לשמור באופן לא מסונן Auth-Header, Tokens או נתונים אישיים. בפועל זה אומר: Redaction (טשטוש) והפעלה רק דרך Feature-Flag או Whitelist (למשל רק עבור Correlation-IDs מסוימות, במסגרת חלון זמן קצר).

יישום נקי בפועל: טשטוש במקום השמטה

באינטגרציות אמיתיות השדות „הקריטיים“ הם לעיתים אלה שנחוצים לדיבוג (למשל מזהים). במקום השמטה גורפת עדיף טשטוש: להחליף חלקית טוקנים, להשאיר באימייל רק את הדומיין, ב־IBAN רק את הספרות האחרונות. כך המקרה נשאר ניתן לשחזור בלי לפזר נתונים מיותרים במערכת הקבצים. בנוסף ה־Snapshot צריך להיות מסומן בבירור כארטיפקט דיבוג ולכלול תקופת שמירה מוגדרת.

אבטחה ותפעול: העברת Headers, שרשראות פרוקסי וזמני פסק־זמן

API של REST כמעט לא מסתיימת ישירות אצל הלקוח. נפוצות שרשראות של Reverse Proxy, TLS‑Termination, WAF או API‑Gateway. מזה נובעים מספר נקודות מעשיות:

• Remote IP: אל תסתמכו בעיוורון על X-Forwarded-For. קבלו אותו רק מפרוקסים מהימנים, אחרת השתמשו בכתובת ה‑Socket הישירה. במדריכי תפעול צריכה להופיע רשימה של אילו hops מוגדרים כ“trusted“.
• Timeouts: אם לפרוקסי יש 30 שניות אך ה‑backend שלכם דורש 2 דקות, יווצרו בקשות רפאים. הגדירו זמני פסק‑זמן בעקביות לאורך השרשרת והחליטו מראש: בקשה סינכרונית או תבנית Job (202 Accepted + נקודת סטטוס).
• Correlation-ID: הכניסו את ה‑Correlation‑ID בכותרות התשובה כדי שמנהלים יוכלו לקשר אותה בין הלוגים לצד הלקוח. אם Gateway מייצר מזהי בקשה משלו — לוגו והצליבו את שני המזהים.
• Fehlertexte: בפרודקשן אין לחשוף פרטים פנימיים. פרטי דיבאג רק במנגנון מבוקר (stage / feature‑flag) ובמקרה של ספק — רק ברשומות הלוג.

Einordnung: Warum RemObjects SDK hier im Vorteil sein kann

במערכות אקוסיסטם של Delphi בונים לעיתים REST-שרתים בעזרת מסגרות קלות יותר (למשל HTTP‑Router מינימליסטי). RemObjects SDK מחדד את יתרונותיו כשכבר קיימת או נדרשת אדריכלות רב‑שכבתית:

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

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

Fazit: Lohnt sich der Aufwand – und wo kippt der Ansatz?

הערך המוסף נוצר כשממשק REST שלכם לא רק „פועל“, אלא ניתן לתפעול לאורך זמן: חוזי JSON יציבים, גרסאות בלי פריחת URL בלתי מבוקרת, שגיאות עקביות ודיבאגינג שאינו רמיזות. בדיוק שם — הגישה עם Context, Correlation‑ID ומיפוי Exceptions מרכזי ב‑RemObjects SDK חזקה.

מגבלות שימוש: אם יש לכם רק נקודת קצה יחידה וקצרה ללא שותפי אינטגרציה, גרסאות מבוססות Media‑Type עלולות להיראות כהעמסת יתר. גם Snapshot‑Logging הגיוני רק אם אתם מיישמים Redaction והפעלה באופן ממושמע. ואם ערמת הפרוקסי שלכם „מייעלת“ או מסירה כותרות — יש ליישר קודם את התשתית, אחרת תדבגו את השכבה הלא נכונה.

כאשר אתם מחדשים סביבת שרתים קיימת של Delphi או צריכים לשלב פתרון תוכנתי קרוב לתהליך בתוך ERP/DMS/CRM בצורה נקייה, מנגנונים אלה לעיתים קרובות מהווים את ההבדל בין „רץ בבדיקה“ ל“רץ בפרודקשן“.

בהקשר המקצועי תופסים גם Delphi REST-API וREST-Server וכן Remobjects Sdk Delphi תפקיד חשוב, כאשר אינטגרציות, זרימות נתונים ופיתוח מתמשך חייבים לפעול באופן מסונכרן ומסודר.

לדון בפרויקט או במהלך מודרניזציה עם Net-Base.