REST API RemObjects SDK-ga: JSON-lõpp-punktide korrektne versioonihaldus ja silumine (Delphi allikakoodilõigud)

Miks „REST API mit RemObjects SDK“ praktikas sageli servadel otsustab

Üks REST API mit RemObjects SDK ei määratle ennast harva „Hello World“-teenuse järgi, vaid seal, kus haldus, pärand- (legacy) süsteemid ja integratsioonid kokku põrkuvad: versioonihaldus katkestusteta, järjekindel veakäitumine kõigi lõpp-punktide ulatuses, reproduseeritav silumine proxy-ahelate korral ja võime probleemolukorras päringuid üheselt korreleerida.

RemObjects SDK pakub selleks palju infrastruktuuri: teenused, sõnumivormingud, serialiseerimine, hosting (nt Windows- und Linux-Services või IIS/Reverse Proxy taga) ja määratletud kohad vigade tsentraalseks käsitlemiseks. Mis aga tihti kasvanud ärirakenduste maastikel puudu jääb, on konsekwentne leping: millised JSON-väljad on stabiilsed? Kuidas signaleerime vigu? Kuidas tuvastame sama päringu, kui see on läbinud load balanceri, TLS-terminatsiooni ja mitu backend-kihi?

Järgmine lähenemine (koos Delphi-snipslitega) näitab RemObjects SDK jaoks robustset joont: JSON-Verträge versionieren, Correlation-ID (Request-ID jälgitavuse jaoks) sundida, Exceptions in HTTP-Status und JSON-Fehlerobjekte tõlkida ning samal ajal mitte mängida silumist ja haldust omavahel vastu. Lisaks vaatame servajuhtumeid, mis reaalses keskkonnas regulaarselt ette tulevad: serveri threading, andmebaasi-päringud koos BDE-ablatsiooniga natiivühenduse kaudu, proxy-päised, timeoudid ja „räpane“ kliendi-payload.

Arhitektuuriotsus: versioonimine meedia-tüübi kaudu, mitte URL-i järgi

Paljud API-d versioonitakse teeradade kaudu nagu /v1/. See on pragmaatiline, kuid pikemaajalistes integratsioonides (nt ERP/DMS/CRM ühendused) viib see tihti URLide dubleerimiseni, topeltreitideni, topelttestideni ja küsimuseni „mida me tegelikult kasutame?“ operatsioonikähandustes.

Alternatiiv on versioonimine Media Type kaudu (Content Negotiation). Klient saadab näiteks Accept: application/vnd.company.order+json;v=2. Server loeb versiooni deterministlikult välja ja kohandab Contract/DTO käitumist. See töötab proxy- ja cache-ahelates, kui päised edastatakse puhtalt. Adminide jaoks on see lisaks hästi kontrollitav: päringut saab reproduseerida Curl/Postmaniga ilma URL-ide erisusteta.

RemObjects SDK ei ole „REST-puristisch“, vaid pragmaatiline teenuse- raamistik. Just sellepärast tasub meedia-tüübi variant ära: võimalus hoida stabiilseid lõpp-punkte ja samal ajal lepinguid edasiarendada. Oluline on, et versiooni alati hinnatakse, otsus tehakse tsentraalselt ja tulemus kantakse teie teenusekonteksti.

Millal Accept-päiste variant võib nurjuda?

Praktikas on kolm tüüpilist murdumispunkti, mida enne tuleks adresseerida:

• Proxy-Policies: mõningad Reverse Proxyd/WAF-reeglid normaliseerivad või filtreerivad Accept-päiseid. Sel juhul langeb teie API vaikimisi versioonile tagasi. Lahendus: kontrollige proxy-reegleid selgesõnaliselt, vajadusel kasutada X-Api-Version päist.
• Client-Libraries: mõned HTTP-kliendid panevad oma Accept-päise ja kirjutavad väärtused üle. Lahendus: toetada lepingu versiooni ka valikulise päringuparameetri kaudu (ainult tagavaralahendusena), või parsida Accept-päist serveripoolselt tolerantsemalt.

Lähtefragment: Request-Context, Correlation-ID, Version und Error-Mapping

Kood on teadlikult üles ehitatud nii, et seda saab integreerida olemasolevatesse RemObjects-serveriprojektidesse: väike konteksti kiht, parser API-versiooni jaoks (saadud Accept-päisest), Correlation-ID mehhanism ja keskne Exception-Mapping. Mõisted:

• Correlation-ID: Iga päringu unikaalne ID, mis tagastatakse vastuses ja millele viidatakse logides.
• Exception-Mapping: Sisemiste Delphi-exceptionside tõlge stabiilseteks, kliendi poolt töödeldavateks veaoobjektideks (sh HTTP-staatus).
• Contract-Version: JSON-lepingu versioon, mis juhib käitumist ja välju.

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.

Zweck: Stabiler Request-Kontext statt „irgendwo im Threadlocal“

Snippeli eesmärk on selge: TApiContext on minimaalne olek, mida soovite edasi anda. RemObjects SDK-s liigub palju läbi serveri-/kanali-konteksti. Heterogeensetes projektides (nt täiendavad worker-lõimed, DB-queue, tausttööde töötlus) on aga eksplicitne edasiandmine sageli robustsem kui implitsiitsed threadlocal’id, sest see teeb samaaegsuse ja konteksti-vahetused nähtavamaks.

Randbedingungen: Accept-headeri variant eeldab, et teie reverse-proxy (nginx, IIS ARR, Traefik) edastab päise muutmata. Mõnes keskkonnas filtreeritakse või kombineeritakse „ebaharilikke“ Accept-päiseid.

Stolperfallen: Versioonihaldus läbi Accept’i on nii hea kui teie testid. Kui kliendid kasutavad teeke, mis kirjutavad Accept’i üle, võib API ootamatult tagastuda vaikolekusse. Legacy-kliendid vajavad vaikimisi fallback’i, kuid see peab olema nähtav monitooringus (nt logihoiatus „Version defaulted“).

Varianten: Kui eelistate versioonimist läbi X-Api-Version: parser on identne, ainult allikas on teine päis. Gateway-de vaatenurgast on see mõnikord lihtsamini kontrollitav.

Integration in RemObjects SDK: Correlation-ID und Exception-Mapping am Service-Einstieg

Tõeline efekt tekib siis, kui rakendate mehhanismi järjekindlalt oma serveri ääres: lugeda kord ühes kohas päringu sisenemisel päistest ja kord erandite väljumisel tõlgendada need stabiilseks response’iks. Sõltuvalt hostimisest (nt RO-HTTP-Server, IIS-hostimine, iseseisev Windows-/Windows- und Linux-Services) erinevad konkreetsetes kohtades olevad hook’id; põhimõte jääb samaks: ehita Context, kutsu äriloogika, mappi erandid tsentraalselt.

RemObjects-projektides töötatakse tihti otse iga teenusemeetodi tasemel. See skaleerub alguses hästi, kuid käigus halduses laguneb: iga meetod ehitab logimise ja vigade käsitlemise erinevalt. Puhtaks lõikeks on teenuse-alus või Dispatcher, mis standardiseerib käitumise.

Praktischer Ablauf (bewusst kurz und implementierungsnah)

1. Correlation-ID lugeda Request-päisest X-Correlation-ID; kui puudub, genereerida serveripoolselt (nt GUID).
2. Contract-versioon lugeda Accept-päisest (või X-Api-Version-päisest).
3. Logida päringu algus: meetod, path, Correlation-ID, kliendi IP-aadress; alustada kestuse mõõtmist.
4. Täita äriloogika; andmebaasi-pöördumised kapseldada võimaluse korral transaktsioonidesse.
5. Püüda erandid: määrata HTTP-olek, luua JSON-veaobjekt, seadistada Response-päis X-Correlation-ID.
6. Logida päringu lõpp: staatus, kestus, vajadusel veakood.

Threading im Server: Warum Correlation-ID ohne Kontext-Disziplin wertlos wird

Sageli esinev Delphi-äärmusjuhtum: teenusemeetod trigeerib asünkroonse töö (nt raporti genereerimine, import, push DMS-i). Sel juhul ei ole algne päringu-lõim enam sama lõim, mis kirjutab hiljem logiridu. Kui Correlation-ID on teada vaid „alguses“, siis kaob jälgitavus.

Pragmaatiline reegel: kõik, mis ei jää rangelt päringu-lõime sees, peab saama konteksti ekspliciitselt edasi. Isegi kui see näib lisavat parameetrite nimekirju, tasub see end ära. Alternatiivselt võib kasutada selgelt defineeritud kontekstobjekti, mida teadlikult worker-itele/tausttöödele antakse (selle asemel, et kasutada globaalseid muutujaid või peidetud singleton’eid).

Tüüpilised kipppunktid RemObjects-/Delphi-serverites:

• DB-ühendused iga lõime kohta: BDE-Ablosung mit nativer Anbindung-ühendused ei ole automaatselt lõime-turvaliselt jagatavad. Ühenduste puhver (Connection-Pool) või iga lõime kohta eraldi ühendus on sageli mõistlikum kui „üldine Connection“.
• Tehingupiirid: Kui päringu raames on mitu omavahel seotud sammu, peab tehing jääma samasse loogilisse üksusesse. Asünkroonne töö ei tohi „eksitusest“ jätkuda samas tehingus.
• Tühistamine: Kui klient katkestab (proksi ajalõpp, brauser suleti), jätkab server sageli töötamist. Mõelge läbi, kas taustatöösel sellisel juhul on ikka mõtet.

Andmejuurdepääs ja veakoodid: 409 ist nicht „auch ein 500“

Integratsiooniprojektides on korrektne veamappimine rohkem kui kosmeetika. See määrab, kas vastaspool (ERP-Connector, ETL-Job, kliendiportaal) suudab õigesti reageerida. Mõned praktilised juhised, mis on Delphi/RemObjects-keskkondades ennast õigustanud:

• 400 Bad Request: Valideerimine, puuduvad/kehtetud parameetrid, JSON ei ole parsitav. Oluline: vastus peab olema stabiilne ka siis, kui päringu keha on rikutud.
• 401/403: Eristage autentimine ja autoriseerimine. 401 tähendab „puudub/vigane identiteet“, 403 „identiteet ok, aga keelatud“.
• 404: Ressurssi ei eksisteeri. Turvalisuse mõttes ettevaatlik: mitte alati ei tohiks avaldada, kas midagi eksisteerib.
• 409 Conflict: Valdkondlik konflikt (nt versioonikonflikt, „olek ei luba seda tegevust“, unikaalse võtme rikkumine, kui see on äriliselt oluline).
• 422 Unprocessable Content: Kui süntaktiliselt on kõik korras, kuid äriline valideerimine ebaõnnestub (mitte iga meeskond ei kasuta 422, kuid see on sageli selgem kui 400).
• 500: Kõik, mida te ei suuda korrektselt klassifitseerida. Sellesse kuulub ka „DB down“, „Timeout“, „Unhandled Exception“.

Delphi-spetsiifiline nipp: Paljud andmebaasi vead tõusevad üles generilistena. Tasub andmejuurdepääsu kihis sihipäraselt kontrollida tuntud olukordi ja teisendada need EApiError-iks. Oluline: ärge kandke kliendisõnumisse üle SQL-fragmente ega sisemisi tabeli-/veerunimesid. Need detailid kuuluvad logisse, mitte response’i.

Silumise nipp: reprodutseeritavad vead läbi „Contract Snapshot“

Ebatavaline, kuid tootmiskeskkonnas äärmiselt kasulik: salvestage vigade korral (või sihipäraselt teatud Correlation-ID-de puhul) „snapshot“ päringu päistest + päringu kehast debug-spool-faili. See ei ole püsilogimine (andmekaitse/maht), vaid kontrollitud tööriist raskesti reprodutseeritavate juhtumite tootmiskeskkonnast järeltestimiseks.

Oluline: snapshot ei tohi kunagi filtreerimata persisteerida autentimispealseid päiseid, tokeneid ega isikuandmeid. Praktikas tähendab see: maskimine (redaction) ja aktiveerimine ainult feature-flag’i või valgesse nimekirja kaudu (nt ainult teatud Correlation-ID-de jaoks, lühikesed ajavahemikud).

Puhas rakendamine praktikas: maskimine, mitte eemaldamine

Tõelistes integratsioonides on just „kriitilised“ väljad sageli need, mida silumiseks vaja läheb (nt identifikaatorid). Üldise eemaldamise asemel on parem maskida: tokenid osaliselt asendada, e-posti puhul jätta alles ainult domeen, IBAN-ist ainult viimased numbrid. Nii jääb juhtum reprodutseeritavaks, ilma et failisüsteemi liigseid andmeid talletataks. Lisaks peaks snapshot olema selgelt märgistatud kui silumisartefakt ja omama määratletud säilitusaega.

Turvalisus ja käitamine: päiste edastamine, proksüüahelad ja timeoutid

Üks REST API ei lõppe harilikult otse kliendis. Tavapärased on kettad, kuhu kuuluvad Reverse Proxy, TLS-terminatsioon, WAF või API-Gateway. Sellest tulenevad praktilised punktid:

• Remote IP: Ära põhine pimesi X-Forwarded-For päisel. Kogu see päis ainult usaldusväärsetest proksüüdest ja muidu kasuta otsest socket-IP-d. Operatsioonijuhendis peab olema kirjas, millised hüpped on „trusted“.
• Timeouts: Kui proksüü ootab 30 sekundit, aga teie backend vajab 2 minutit, tekivad kummituspäringud. Määra timeoutid kogu ahela ulatuses ühtselt ja otsusta: sünkroonne päring või tööprotsess (202 Accepted + Status-Endpunkt).
• Correlation-ID: Pane Correlation-ID vastuse päistesse, et administraatorid saaksid seda logidest ja kliendipoolelt kokku viia. Kui gateway kasutab oma päringu-IDsid: logi ja seosta mõlemad ID-d.
• Fehlertexte: Produktiivkeskkonnas ära avalda sisemisi detaile. Debug-detailid ainult kontrollitult (stage/feature-flag) ja kahtluse korral ainult logis.

Paigutus: miks RemObjects SDK siin eeliseks võib olla

Delphi-ökosüsteemides ehitatakse REST-servereid tihti kergemate raamistikuga (nt minimalistlikud HTTP-ruuterid). RemObjects SDK mängib oma tugevust välja, kui teil on juba olemas või on vaja mitmekihilist arhitektuuri:

• Selged teenusepiirid: Teenuse meetodid on ekspliitsed, kontraktid on versioonitavad.
• Transpordid ja serialiseerimine: Võite suhelda JSON-iga, aga ka kasutada teisi sõnumivorme (sõltuvalt ülesseadest), ilma äriloogikat kokkukastetamata.
• Käitamine: Hostimise valikud ja integratsioon olemasolevate Windows- ja Linux-teenustega on planeeritavad, sealhulgas puhtad roll-outid.

Näidatud lähenemine täiendab seda osadega, mis igapäevatöös sageli puuduvad: ühtlustatud veaoobjektid, deterministlik versioonimine ja korreleeritav logimine. Eriti individuaalse ärisoftware puhul, mille elutsükkel on pikk, säästab see aega nii uuendustel kui väliste süsteemide integreerimisel.

Kokkuvõte: kas vaev on seda väärt — ja kus see lähenemine ebaotstarbekaks muutub?

Kasulikkus tekib siis, kui teie REST-liides ei ole lihtsalt „töötab“, vaid püsivalt haldatav: stabiilsed JSON-lepingud, versioonihaldus ilma URL-äraeksimiseta, jälgitavad vead ja debugimine ilma arva-mänguta. Just selles punktis on lähenemine, mis kasutab Contexti, Correlation-ID-d ja keskset Exception-Mappingut RemObjects SDK-s, tugev.

Kasutuspiirid: Kui teil on ainult üksainus, lühiajaline endpoint ilma integratsioonipartneriteta, võib meediumitüübi versioonimine kiiresti tunduda üleplaneerimisena (Overengineering). Ka snapshot-logging on mõistlik alles siis, kui andmete peitmine (redaction) ja selle aktiveerimine on distsiplineeritult rakendatud. Ja: kui teie proksüü-stack „opimeerib“ või eemaldab päiseid, peate esmalt infrastruktuuri korda tegema, vastasel juhul debugite vale kihti.

Kui peate moderniseerima olemasolevat Delphi-serverimaastikku või integareerima protsessikeskset tarkvaralahendust korrektselt ERP/DMS/CRM-iga, on just need mehhanismid tihti vahe „töötab testis“ ja „töötab tootmises“ vahel.

Tehnilises kontekstis mängivad samuti Delphi REST-API ja REST-Server ja Remobjects Sdk Delphi olulist rolli, kui integratsioonid, andmevood ja edasine arendus peavad sujuvalt koos töötama.

Arutage projekti või moderniseerimisprojekti koos Net-Base.