İşletmeler için Delphi ile REST Sunucu Mimarisi

Bugün birçok şirket benzer bir başlangıç noktasında: Zaman içinde büyümüş bir kurumsal uygulama (çoğunlukla Delphi/VCL) merkezi süreçleri temsil ediyor, ancak aniden yeni kanallara hizmet vermesi bekleniyor. Bir Müşteri portalı veri ve işlemler gerektirir, mobil kullanıcılar güvenli erişimler bekler, üçüncü taraf sistemler (ERP, DMS, CRM, BI) entegrasyon talep eder. Bu durumda bir REST-API mantıklı bir adım gibi görünür. Pratikte ise API girişimleri nadiren HTTP veya JSON yüzünden başarısız olur — çoğunlukla Client, Server ve veri katmanı arasındaki belirsiz sorumluluk dağılımı yüzündendir.

Dayanıklı bir REST-Server mimarisi ile Delphi’in bir arada çalışması, mevcut veritabanı tablolarının üstüne “birkaç endpoint” koymakla oluşmaz. Bu, şirketin iş kurallarını, güvenlik gereksinimlerini, veri mülkiyetini, işlem sınırlarını ve işletim konseptlerini birlikte ele almasıyla ortaya çıkar. REST-Server böylece iş mantığı ile tüketiciler (masaüstü istemci, portal, servisler, entegrasyon ortakları) arasındaki kararlı bir sözleşme katmanı haline gelir. Tam da burada Delphi gücünü gösterir: hızlı geliştirme, sağlam çalışma zamanı, performanslı natif kod, iyi veritabanı entegrasyonu (ör. BDE-Ablösung ile natif bağlantı) ve iş mantığını kontrollü biçimde kütüphanelere ya da server modüllerine kapsülleme olanağı.

Bu metin, şirketlerin REST-Server’ları Delphi ile nasıl planlamaları gerektiğini; böylece iş açısından tutarlı kalabileceklerini, mevcut sistem manzaralarına uyum sağlayabileceklerini ve işletimde hata kaynağı olmaktan kaçınabileceklerini anlatıyor. Odak noktası mimari ilkeler, modernizasyon projelerindeki tipik tuzaklar ve güvenlik, veri erişimi, versiyonlama ile gözlemlenebilirlik için somut bileşenlerdir.

Neden bir REST-API kurumsal bir mimari kararıdır

Klasik bir Client-Server dünyasında birçok kural masaüstü istemciye dağıtılmış olarak vardı: doğrulamalar, durum değişiklikleri, hesaplamalar, hatta bazen yetkilendirmeler. Tek bir istemci olduğu sürece bu çok kritik değildi — iş açısından hoş olmayan ama yönetilebilir bir durumdu. Aynı iş nesnelerine birden fazla tüketici erişmeye başlayınca bu model çöker:

• Bir portal, istemci tarafı doğrulamaları “kullanamaz”.
• Mobil uygulamalar çevrimdışı çalışabilmeli, ama iş kurallarını kopyalamamalıdır.
• Entegrasyonlar stabil, versiyonlanmış sözleşmeler ve açık hata semantiği gerektirir.
• Uyumluluk (compliance) izlenebilir erişimler, rol modelleri ve audit yeteneği talep eder.

API, iş mantığının, yetkilerin ve veri erişiminin bir araya geldiği yer olur. Bu nedenle mimarisi, sisteminizin uzun vadede genişletilebilir kalıp kalmayacağını — yoksa sadece yeni teknik borçlar mı üreteceğinizi — belirler.

Delphi: REST-Server için bir platform olarak güçlü yanları ve tipik kullanım senaryoları

Delphi sıklıkla masaüstü uygulamalarla ilişkilendirilir. Ancak REST-Server’lar için de oldukça uygundur; özellikle mevcut iş mantığının yeniden kullanılması veya performans gerektiren servisler söz konusuysa. B2B ortamlarında tipik kullanım senaryoları:

• Mevcut yazılım için API katmanı: Mevcut Delphi iş uygulaması UI olarak kalır; REST-Server yeni tüketiciler için veri erişimini ve kuralları kapsüller.
• Portal / müşteri bölümü için backend: Web portal, dahili süreçlerle aynı kural çekirdeğini kullanan REST endpoint’lerini tüketir.
• Entegrasyon ve arayüz server’ı: ERP/DMS/CRM bağlantıları, import/export, olay işleme, zamanlanmış işler.
• Linux-Services veya Windows Services: Uzun süren süreçler, kuyruk-tüketiciler, zamanlayıcılar, belge iş akışları.

Önemli olan framework etiketi değil; katmanlama, eşzamanlılık, hata yönetimi ve dağıtım disiplinidir. Delphi hem hızlı iterasyonlar sunar hem de özenli, modüler bir mimari mümkün kılar — yeter ki bilinçli planlama yapılsın.

Schichtenmodell: Layer-3 mimarisi kalıcı API’ler için temel

Kurumsal yazılımlar için net, yalın bir katman modeli işe yaramıştır. Delphi ortamında bu genellikle Layer-3 mimarisi olarak tanımlanır. Terimler değişse de sorumluluklar net olmalıdır:

1) API-/Transport-Layer (HTTP, Serialization, Routing)

Bu katman HTTP, protokol seviyesi kimlik doğrulama, request/response formatları, routing, status kodları, Content-Type, sıkıştırma ile ilgilenir. Bu katmanda iş kuralları yer almamalıdır. Amaç: değiştirilebilirlik ve test edilebilirlik. Daha sonra REST-API’yi ek protokollerle (ör. WebSocket, gRPC-benzeri desenler, Server-Sent Events) genişletmek istediğinizde, iş çekirdeğinin stabil kalması gerekir.

2) Domain-/Service-Layer (İş mantığı, Use Case’ler, Yetkiler, Transaksiyonlar)

İşin doğrusu burada yaşar: durum makineleri, hesaplamalar, tutarlılık kontrolleri, tenant kuralları, iş aksiyonlarına yönelik yetki kontrolleri. Bu katman UI’dan bağımsız olmalı ve mümkün olduğunca HTTP bilgisi içermemelidir. İdeal olarak „Siparişi onayla“, „Ticket kapat“, „Fatura oluştur“ gibi Use Case’leri uygulamalısınız; sadece tablolar üzerinde CRUD yapmak yerine.

3) Data-Access-Layer (Repository’ler, SQL, FireDAC, Mapping)

Bu katman kalıcılığı kapsüller: SQL, Stored Procedure’ler, işlem yönetimi, kilitleme politikaları, connection-pooling, DB’ye özgü ayrıntılar. Delphi ortamında BDE-Ablosung mit nativer Anbindung sıkça pragmatik tercih olur; özellikle migrasyonlarda (BDE-Ablösung) ve heterojen veritabanlarında (SQL Server, PostgreSQL, MariaDB, Firebird). Önemli nokta: Data-Access-Layer HTTP bilgisi içermemeli ve iş kararları vermemelidir.

Bu model gevşek bağlılığı azaltır: Veri modelindeki değişiklikler API’nin yeniden yazılmasını zorunlu kılmaz ve yeni istemciler otomatik olarak aynı mantığı devralır. Özellikle Delphi Modernisierung sürecinde, yerleşik masaüstü uygulamaları işletmeyi kesintiye uğratmadan adım adım ayrıştırmak için bu temel gerekir.

Kurumsal yazılım için API tasarımı: CRUD değil, iş sözleşmeleri

Birçok API /customers, /orders, /documents gibi endpoint’lerle başlar ve CRUD uygular. Bu bazı iç araçlar için yeterli olabilir, ancak kurumsal yazılımda hızla yetersizleşir. İş süreçleri durum değişiklikleri, kurallar, yan etkiler ve yetkilendirmelerden oluşur.

Kaynakları, eylemleri ve durumları düzgün modelleyin

Daha iyi bir desen kaynaklar ile net eylemler kombinasyonudur, örn:

• Kaynak okumak: GET /orders/{id}
• Eylem tetiklemek: POST /orders/{id}/release
• Belge oluşturmak: POST /orders/{id}/documents/invoice
• Durum kontrolü: GET /orders/{id}/status

Böylece API sözleşmesinde „Onaylama“nın basit bir alan güncellemesi olmadığı görünür. Sunucu doğrulamaları, yetkileri, transaksiyonları, audit ve yan işlemleri merkezi olarak uygulayabilir.

Hata semantiği ve doğrulama: istemciler için öngörülebilir kılın

Kurumsal istemciler hataları ayırt edebilmelidir: doğrulama hataları (400), yetki yok (403), paralel değişiklikten kaynaklanan çakışma (409), işsel reddetme (çoğunlukla 409 veya 422), geçici backend sorunları (503). Tutarlı bir hata yapısı önemlidir; örn. hata kodu, mesaj, isteğe bağlı alan ipuçları ve bir korelasyon-ID. Böylece bir portal anlamlı bildirimler gösterebilir ve aynı zamanda destek ile işletme verimli biçimde izleyebilir.

Güvenlik: Kimlik doğrulama (Authentication) ile Yetkilendirme (Authorization) aynı şey değildir

B2B bağlamında güvenlik nadiren şifreleme yüzünden başarısız olur; daha çok kimlik, roller ve işsel yetkilerin ayrılmamasından kaynaklanır. Bir REST-Server mimarisi bu iki düzeyi ayırmalıdır:

Kimlik doğrulama (bu kim?)

Yaygın yöntemler, TLS ile kombine edilmiş token tabanlı yaklaşımlardır (örn. JWT veya opaque token’lar). Önemli noktalar: token yaşam süresi, refresh mekanizması, roller değiştiğinde token iptali, portal ile iç sistemler için farklı Identity-Provider kullanımı gerekip gerekmediği. Delphi-Server’lar burada hem Resource-Server olarak davranabilir hem de kuruluma göre token düzenleyebilir. Birçok kurumsal ortamda mevcut Identity sistemlerine entegrasyon (örn. AD/LDAP, SSO çözümleri) merkezidir.

Yetkilendirme (bunu yapabilir mi?)

Yetkilendirme Domain-/Service-Layer’da olmalıdır. Roller ve haklar nadiren yalnızca teknik olur; bunlar tenant, lokasyon, organizasyon birimi, sözleşme durumu veya süreç aşamasına bağlıdır. İyi uygulamalar:

• Roller modeli (örn. Admin, Operasyon, Auditor) temel olarak
• İşsel politikalar („faturayı yalnızca X durumdayken oluşturabilir“, „sadece kendi kayıtlarını görebilir“)
• Tenant yetenekleri varsayılan: her istek tenant-bağlamı gerektirir
• Auditing: kim hangi işlemi ne zaman tetikledi

API yalnızca „erişim verildi/reddedildi“ döndürmemeli, aynı zamanda sunucuda parametre oyunları ile başka tenant verilerinin görünmesini engellemelidir. Bu bariz görünse de, hızla „tabloları HTTP’ye koyma“ hatası yapıldığında olgun sistemlerde en sık rastlanan mimari hatalardan biridir.

FireDAC ile veri erişimi: transaksiyonlar, pooling ve veritabanı stratejisi

Kurumsal uygulamalarda veri erişimi istikrar faktörüdür: yük zirveleri, deadlock’lar, uzun raporlar, paralel güncellemeler, toplu importlar. FireDAC Delphi ekosisteminde farklı veritabanlarını tek bir erişimle yönetmek için denenmiş bir yapı taşır. REST-Server mimarisi için özellikle şu noktalar kritiktir:

Use Case başına transaksiyon sınırları

Bir REST-API tipik olarak request bazlıdır. Bu, „Use Case başına bir transaksiyon“ ile iyi eşleşir: Bir istekte transaksiyon açılır, işsel operasyonlar yapılır, sonra commit/rollback. Önemli: Her endpoint’i otomatik olarak transaksiyona sokmayın; yazma işlemlerinde ise tutarlı olun. Okuma endpoint’leri de tutarlı görünümler gerekiyorsa izolasyon seviyesine bağlı olarak transaksiyon gerektirebilir.

Connection stratejisi ve paralellik

Server paralelliği demek: aynı anda çok sayıda request ve her biri DB erişimi. Bu nedenle planlayın:

• sınırlı, izlenen pool boyutları
• sorgular ve bağlantılar için timeout’lar
• uzun süren operasyonlar için net kurallar (işleri/worker’lara dışlama)

Sık yapılan hata: ağır raporları veya büyük veri ihracını, interaktif portal isteklerini de karşılayan aynı API örneğinde senkron olarak çalıştırmak. Daha iyisi ayrıştırmadır: interaktif ile batch/async’i ayrı tutmak.

Veritabanı modernizasyonu API planlamasının parçası olarak

Stokta hâlâ eski veri erişimleri varsa (ör. BDE), API bir katalizör olur: Net veri erişim sınırları konmasını zorunlu kılar. Kontrollü bir geçişe FireDAC yönelmek riskleri azaltır ve taşınabilirliği artırır (PostgreSQL, MariaDB, SQL Server). Bunu „Big Bang“ şeklinde değil, kademeli planlayın: yeni server Use Case’leri yeni Data-Access-Layer’ı kullanırken eski parçalar zamanla uyum sağlar.

Versiyonlama ve geriye dönük uyumluluk: API sözleşmeleri korur

Şirketler genellikle Breaking Change’lerin maliyetini hafife alır. Bir müşteri portalı, partner sistemi veya Windows-servisi API’nize bağlıysa „hızlıca“ alan adını değiştiremezsiniz. Bu yüzden temiz bir versiyonlama stratejisi zorunludur.

Versiyonlama için pragmatik kurallar

• Versiyon olmadan Breaking Change yok: alanları yeniden adlandırmayın/kaldırmayın, endpoint’leri farklı yorumlamayın.
• Değiştirmek yerine genişletin: yeni alanlar ekleyin, eskileri deprecated olarak işaretleyin.
• Uyumlu varsayılanlar: yeni zorunlu alanlardan kaçının veya bunları sunucu tarafında türetin.
• Açık versiyonlama: örn. /v1/… veya header ile; yöntemden ziyade tutarlılık önemlidir.

Delphi ekipleri için bu, DTO’ları (Data Transfer Objects) stabil tutmak ve mapping’i kasıtlı yapmak anlamına gelir; domain objelerini 1:1 serileştirmek yerine. Başlangıçta maliyeti artırır ama uzun vadede destek maliyetlerini düşürür.

Gözlemlenebilirlik: Logs, metrikler ve trace’leri baştan planlayın

Üretim ortamında „bende çalışıyor“ demek, hatalar yeniden üretilemiyorsa değersizdir. Özellikle birçok tüketiciye hizmet eden REST-Server’lar için en azından şu gözlemlenebilirlik gereklidir:

Yapılandırılmış logging ve korelasyon-ID

Her isteğin bir korelasyon-ID’si olmalı (geleni kullanma veya oluşturma) ve loglarda görünmeli. Log girdileri yapılandırılmış olmalı (örn. JSON-Log) ki merkezi sistemlere ingest edilebilsin. En az şu bilgiler önemli:

• Request metodu, route, status kodu, süre
• Kullanıcı/tenant bağlamı (pseudonimleştirilmiş/uyumlu)
• DB süresi ve hata sınıfı
• Destek için korelasyon-ID

Kapasite ve hata trendleri için metrikler

Ölçekleme ve stabilite için metriklere ihtiyacınız var: dakika başına istek sayısı, p95/p99 gecikmeler, endpoint’e göre hata oranları, DB-pool kullanım oranı, kuyruk uzunlukları. Bu „Cloud-Native aşırılığı“ olmak zorunda değil, ama sayılar olmadan performans tartışmaları görüşe dönüşür.

Hata ve istisna yönetimi mimari bileşeni olmalı

Delphi-Exceptions kontrolsüzce dışarı sızmamalıdır. Merkezi bir Exception-Middleware (veya global handler) istisnaları tutarlı hata yanıtlarına çevirmeli, destek-ID ve uygun HTTP kodları eklemelidir. İçeride stacktrace’ler güvenli loglara gitmeli, client yanıtlarında yer almamalıdır.

Senkron vs. asenkron: Uzun süren işleri REST cevaplarından çıkarın

Birçok kurumsal süreç „200 ms içinde Request/Response“ değil: PDF üretimi, veri importu, entegrasyon çalıştırmaları, mutabakatlar, toplu değişiklikler, arşivleme. Bu iş yükleri genellikle senkron bir REST endpoint’ine ait değildir; thread bağlar, timeout’lara yol açar ve kullanıcıyı engeller.

İş (Job) deseni

Etkin yaklaşım: Bir endpoint bir işi başlatır ve server hemen bir Job-ID döner. Başka bir endpoint durum/sonucu sağlar. İsteğe bağlı callback/webhook bilgilendirebilir. Delphi ile bu, worker servisleri, bir Job tablosu ve net bir durum makinesi ile uygulanabilir. Avantaj: stabilite ve planlanabilir ölçeklendirme.

Kuyruklar ve servisler

Ortamınıza bağlı olarak bir Message Queue mantıklı olabilir, ama zorunlu değildir. Önemli olan prensip: interaktif API’ler yanıt verimli kalır, batch süreçler kontrol altında, tekrarlanabilir ve izlenebilir şekilde çalışır — deployment’a göre Windows Services veya Linux Services olarak.

Kurumsal dağıtım: Windows, Linux, Container, On-Prem

Bir REST-Server mimarisi ancak işletilebilir olduğunda „tam“ sayılır. Şirketler büyük farklılık gösterir: klasik Windows sunucular, sanallaştırılmış Linux hostlar, container platformları, katı ağ zonları, proxy ve sertifika talepleri. Delphi burada esnektir, yeter ki bağımlılıklar temiz yönetilsin.

Konfigürasyon ve Secrets

Konfigürasyon ortam-bağımlı olmalı (Dev/Test/Prod). Kimlik bilgileri EXE’de veya repoda olmamalı. İlgili platformun Secrets-Management’ını kullanın ve konfigürasyon değerlerini kod sürümlerinden ayırın. Ayrıca DB parolası ve API anahtarları için rotasyonları, sistemi yeniden inşa etmeden yapabilmeyi planlayın.

Release ve rollback stratejileri

Bir API’ye birden fazla tüketici bağlıysa kontrollü release’lere ihtiyacınız var: DB değişiklikleri için migration script’leri, kademeli etkinleştirme için feature-toggle’lar, net rollback yolları. Özellikle veritabanı değişiklikleri geri almayı destekleyecek şekilde geriye dönük uyumlu olmalıdır; aksi takdirde sunucu versiyonunu rollback etmek zordur.

Mevcut yazılımla entegrasyon: Big Bang yerine kademeli modernizasyon

Birçok Delphi ortamında iş çekirdeği değerlidir, fakat teknik olarak „yapışmış“ durumdadır: UI’ye yakın veri erişimleri, global durumlar, karışık sorumluluklar. REST-API burada hem risk hem de fırsat sunar. Hedef, makul çabayla ölçülebilir iyileşme getiren bir yol haritası olmalıdır.

API’ler için Strangler yaklaşımı

Her şeyi baştan yapmak yerine, gerçek fayda sağlayan iş ara yüzlerini tanımlayın: örn. „Müşteri portalı için sipariş durumu ve belgeler“, „mobil kullanıcılar için temel veri lookup’u“, „ERP muhasebe kayıtları için arayüz“. Bu Use Case’ler yeni API fonksiyonları olarak uygulansın — domain katmanı ve data-access dahil. Eski istemci aynı server Use Case’leri kullanacak şekilde adım adım yönlendirilebilir; UI’nin hemen yeniden yazılması şart değildir.

Ortak iş mantığı: mantıklı ama kontrollü

Delphi ile iş mantığı hem server’da hem mevcut uygulamalarda paylaşılabilir. Bu bir köprü olabilir, ancak tehlikeler taşır: UI bağımlılıkları ortak mantığa sızarsa ayrışmayı kaybedersiniz. Açık bir kural yardımcı olur: Ortak kullanılabilir olan yalnızca UI içermeyen, global durum içermeyen, net arayüzleri ve test edilebilir birimleri olan mantık olmalıdır. Diğer her şey ayrık kalmalıdır.

REST-Server projelerinde tipik hatalar — ve nasıl önlersiniz

„Biz sadece tabloları yayınlıyoruz“

Endpoint’ler doğrudan tabloları aynalıyorsa, istikrarsız bir sistem oluşur: her DB-refaktoring API için breaking change olur, iş kuralları client’larda kopyalanır ve parametre kontrolleri olmayan yerlerde güvenlik açıkları artar. Daha iyi olan: sözleşmeyi stabil hale getiren Domain-Use-Case’ler ve DTO’lar kullanmaktır.

İşsel yetkilendirmeler yalnızca client’ta

Client’lar değiştirilebilir ve manipüle edilebilir. Yetkilendirme server’da olmalı ve teknik rollerin ötesinde iş kurallarını içermelidir.

Yanlış bir paralellik stratejisi

Paralel güncellemeler olur: iki operatör, portal ve dahili client veya bir import işi. Optimistic Locking (örn. RowVersion/Timestamp), çakışma kodları (409) ve net merge kuralları yoksa veri kaybı veya „son yazan kazanır“ hataları ortaya çıkar.

Uzun süren işler interaktif endpoint’leri bloke eder

Senkron PDF üretimi veya dışa aktarımlar timeout’lara ve donma deneyimine yol açar. İş pattern’ı ve durum endpoint’leri daha iyidir.

Gözlemlenebilirlik sonradan ekleniyor

Korelasyon-ID, yapılandırılmış loglar ve metrikler olmadan her arıza bir arama operasyonuna dönüşür. İzlenebilirlik bir lüks değil, işletme gerekliliğidir.

REST-Server mimariniz için somut kontrol listesi

• Katmanları net ayırın: Transport (HTTP), Domain (Use Case’ler), Data Access (FireDAC/SQL).
• API’yi bir sözleşme olarak anlayın: DTO’ları stabil tutun, versiyonlama planlayın, Breaking Change’lerden kaçının.
• Güvenliği iki aşamada ele alın: Kimlik doğrulama (token) artı yetkilendirme (iş politikaları, tenant).
• Transaksiyonları bilinçli belirleyin: Use Case başına, timeout’lar, çakışma stratejileri.
• Uzun süren işler asenkron olsun: Jobs/Worker’lar, Windows veya Linux servisleri.
• Gözlemlenebilirliği baştan inşa edin: Korelasyon-ID, yapılandırılmış loglar, metrikler, merkezi hata yönetimi.
• Dağıtımı gerçekçi planlayın: Konfigürasyon/Secrets, rollback, veritabanı migrasyonları.
• Modernizasyonu iteratif yapın: katma değerli Use Case’leri önceleyin, eski parçaları adım adım ayrıştırın.

Sonuç: REST-Server ancak işletme ve iş mimarisi olarak değer üretir

REST-Server mimarisi ile Delphi bir arada en etkili olduğunda, bunun yalnızca „teknik bir yüzey“ değil; süreçler, veriler ve kanallar arasında bağlayıcı bir çekirdek olarak anlaşıldığı zamandır. Belirleyici olan, temiz katmanlar (Layer-3 mimarisi), işsel olarak modellenmiş endpoint’ler, tutarlı güvenlik ve tenant mantığı ile versiyonlama, monitoring ve kontrollü paralellik içeren bir işletim modelidir. Böylece API istikrarlı bir platforma dönüşür: portallar, entegrasyonlar, servisler ve aşamalı Delphi Modernisierung için — gelişmiş bir sistemin işsel özünü riske atmadan.

Mevcut Delphi ortamınızda (veritabanı stratejisi, FireDAC, servisler ve işletim dahil) dayanıklı bir REST-API’nin nasıl kurulabileceğini değerlendirmek isterseniz, bize şu adresten ulaşabilirsiniz: https://net-base-software-gmbh.de/kontakt/