Desenvolupar servidors REST amb Delphi: arquitectura, seguretat i explotació a la pràctica

Qui vulgui desenvolupar un REST-Server amb Delphi rarament persegueix un fi en si mateix dins les empreses. Sovint es tracta d’interfícies robustes entre sistemes heretats, portals, serveis i bases de dades —amb requisits clars d’operació, seguretat i mantenibilitat. El decisiu no és tant la rapidesa amb què respon un primer endpoint, sinó si el servei es manté estable en el dia a dia: patrons d’error rastrejables, accès a les dades controlat, autenticació neta, responsabilitats clares dins l’arquitectura i un desplegament que encaixi amb entorns Windows i Linux.

Delphi resulta pragmàtic en moltes organitzacions: la lògica de negoci existent es pot reutilitzar, el rendiment sol ser suficient i hi ha diversos camins per implementar APIs basades en HTTP. A la pràctica, les opcions es diferencien menys en “pot fer REST” i més en transparència i operació: amb quina consistència es poden implementar logging, timeouts, regles de reverse proxy, versionat, documentació OpenAPI i mecanismes de seguretat?

Aquest article situa els principals enfocaments de Delphi i mostra què haurien de considerar la direcció IT, els administradors i els responsables tècnics del projecte: des del disseny d’API passant per la seguretat i l’accés a dades amb BDE-Ablösung amb connexió nativa fins a observability (logs, mètriques, tracing) i desplegament com a serveis Windows o Windows- i Linux-Services. L’objectiu és una base robusta per a integracions amb ERP, DMS, CRM o portals de clients —sense posar l’interior dels frameworks al centre.

Quan compensa especialment un REST-Server amb Delphi

Un backend Delphi-REST sol ser encertat quan Delphi ja està establert a l’empresa o quan es vol reutilitzar la lògica de negoci i els accès a dades d’aplicacions existents. Situacions típiques B2B:

• Fer la software existent apte per API: Una aplicació VCL o un nucli client-server rep una capa REST per tal que portals, sistemes externs o serveis interns puguin accedir de forma estandarditzada.
• Integració i desacoblament: Diversos consumers (escriptori, web-portal, batch, partner) han d’utilitzar els mateixos processos de negoci sense accès directe a la base de dades ni intercanvi de fitxers.
• Modernització per fases: Primer introduir una API estable i després reestructurar gradualment la UI, mòduls o la base de dades. L’API es converteix en una frontera controlada i redueix efectes secundaris.
• Operació i seguretat: Les APIs HTTP es poden operar còmodament darrere de reverse proxies, autenticar de manera centralitzada i integrar en pilars de monitoring.

Important és gestionar les expectatives: REST és una interfície d’integració, no un substitut de coherència funcional. Qui comenci sense un model de domini clar, límits de transacció definits o responsabilitat de dades explícita, construirà ràpidament una API accessible però cara de mantenir i donar suport a mig termini.

REST-Server amb Delphi: opcions a vista d’ocell

Delphi ofereix diversos camins per implementar un servei REST. Per a decisors la qüestió no és tant “quin és més modern”, sinó: Quant encaixa amb l’estructura de l’equip, el model d’operació, la vida útil prevista i els requisits de compliance?

Delphi WebBroker: esvelt, transparent, fàcil de controlar

WebBroker és un framework consolidat de Delphi per aplicacions HTTP. Està a prop del protocol (request/response), és per això fàcil d’entendre i atractiu en molts escenaris B2B on cal tractament d’errors controlat, maneig net dels headers i una pila de components limitada. WebBroker es pot operar habitualment darrere d’un reverse proxy que termini TLS i apliqui regles de seguretat centrals.

Conseqüència pràctica: moltes funcionalitats de comoditat (convencions de routing, cadenes de middleware, manteniment d’OpenAPI) cal implementar-les de manera estructurada. Això no és un inconvenient si els estàndards d’arquitectura ja són prioritaris.

Delphi Horse: routing i middleware per estàndards d’API clars

Delphi Horse és lleuger i parteix d’un routing entenedor combinat amb el principi de middleware. Middleware vol dir aquí passos de processament reutilitzables “al voltant” de l’endpoint, per exemple autenticació, logging, límits de rate o validació de requests. Per a molts equips és un enfocament productiu perquè permet imposar estàndards de manera centralitzada.

Per a l’operació és important: definir d’hora un format d’errors uniforme, timeouts, mides màximes de request i un estàndard de logging. Sense aquestes directrius el sistema pot funcionar però esdevé innecessàriament costós en suport i ampliacions.

RAD Server: enfocament de plataforma amb components integrats

RAD Server (abans EMS) aposta més per un model de plataforma amb funcions integrades com gestió d’usuaris i altres components. Pot encaixar en escenaris on diversos clients necessiten un backend comú i es volen aprofitar funcions de plataforma. Per a APIs d’integració purament tècniques no és necessàriament la millor opció; aquí sovint pesen més la transparència, les dependències reduïdes i un model d’operació esvelt.

DataSnap: valorar realment les instal·lacions existents

DataSnap està present històricament en moltes paratges Delphi i pot exposar endpoints de tipus HTTP/REST. Per a nous projectes cal valorar si s’ajusta a l’estil d’API previst, a l’autenticació (p. ex. JWT), a OpenAPI/Swagger i als requisits moderns d’operació. Sovint la via pragmàtica és: reutilitzar la lògica existent però posar una capa externa REST ben definida que imposi estàndards de seguretat, logging i versionat.

Arquitectura que aguanta en operació i manteniment

Un error freqüent en projectes REST és “el handler ho fa tot”: es llegeixen paràmetres HTTP, es construeix SQL directament, s’implementen regles de negoci i a sobre s’afegeix logging. Això sembla ràpid al principi però condueix a codi difícil de testar i canvis inestables.

En entorns empresarials funciona millor una estratificació clara. Una estructura pragmàtica habitual és una arquitectura Layer-3 (tres capes) que separa responsabilitats:

Capa de transport: HTTP, auth, validació, format de resposta

Aquí s’accepta la request, es fa la validació bàsica i es genera un format de resposta coherent. En aquesta capa van també l’autenticació i l’autorització (qui pot fer què) així com regles tècniques com límits de request, CORS o l’assignació de Correlation-IDs (identificadors únics per a cada petició per facilitar el rastreig).

Capa de domini: casos d’ús de negoci en comptes de lògica d’endpoint

El domini encapsula processos de negoci com “crear comanda”, “canviar estat” o “associar document”. És decisiu que aquesta lògica sigui el més independent possible del framework HTTP. Així la mateixa capa de domini pot ser reutilitzada per un Windows- i Linux-Services, un daemon Linux o un procés batch sense duplicar lògica.

Persistència i integració: FireDAC, base de dades, ERP/DMS/SMTP

Aquesta capa reuneix l’accés a bases de dades i sistemes externs. Per a Delphi el stack habitual d’accés a dades és BDE-Ablosung mit nativer Anbindung per connectar netament amb PostgreSQL, SQL Server, MariaDB/MySQL o Firebird. L’important no és només “usar FireDAC”, sinó establir regles vinculants: gestió de connexions, límits de transacció, timeouts, vinculació de paràmetres, traducció d’errors tècnics a codis d’error d’API i estratègies de reintents uniformes allà on tinguin sentit funcional.

Disseny d’API: estable durant anys, no només fins al Go-live

En entorns B2B una API és una interfície mantinguda a llarg termini. El concepte clau és la compatibilitat: els consumers confien en camps, codis d’estat i semàntica. Com més clares siguin aquestes regles, menys esforç suposarà la integració, el suport i les releases.

Recursos i rutes: coherència abans que creativitat

Les APIs estables acostumen a ser orientades a recursos: “/customers”, “/orders/123”, “/orders/123/items”. Les accions de procés es poden representar com subrecursos o endpoints d’acció justificats, per exemple “/orders/123/cancel” si un model CRUD pur no és adequat funcionalment. L’important és una convenció única, documentada i usada per tot l’equip.

Mètodes HTTP i codis d’estat: senyals clars per als consumers

Una API fàcil d’integrar utilitza la semàntica HTTP esperable: GET per consultes, POST per crear, PUT/PATCH per modificar, DELETE per eliminar. Igual d’important és un comportament d’errors consistent. Per a l’operació és útil un objecte d’error estandarditzat amb:

• HTTP-Status (p. ex. 400, 401, 403, 404, 409, 422, 500)
• codi d’error estable (llegible per màquina, documentat)
• Correlation-ID (per una assignació ràpida als logs)
• detalls opcionals (p. ex. errors de camp en validació)

Un escull habitual són respostes “200 OK” amb text d’error al body. Això complica les integracions i provoca lògica client més fràgil.

Versionat i ampliació compatible

El versionat és un problema de procés i comunicació, no només tècnic. Enfocaments comuns són el versionat a la URL (p. ex. “/api/v1”) o mitjançant headers. En moltes empreses la regla més important és: ampliar de forma compatible. Afegir camps nous acostuma a ser inofensiu; eliminar o reinterpretar camps requereix una nova versió i un període de migració clarament comunicat. Això redueix fallades d’integració i fa les releases planificables.

Seguretat: autenticació, autorització, superfícies d’atac

Un servei REST pot ser una possible via d’atac. Molts problemes de seguretat no provenen de la manca de xifrat, sinó d’errors de detall: permisos massa amplis, temps de vida massa llargs dels tokens, endpoints d’administració sense protegir, regles CORS incontrolades o logs amb dades sensibles.

TLS i reverse proxy: responsabilitats clares a la xarxa

En configuracions típiques TLS es termina al reverse proxy (p. ex. Nginx, Apache o Microsoft IIS com a reverse proxy). El servei Delphi s’executa interiorment sobre HTTP i només és accessible des de la xarxa interna. Són importants regles netes per a “X-Forwarded-For” i “X-Forwarded-Proto” perquè la IP del client i el protocol s’interpretin correctament. Aquesta informació és rellevant per a auditories, rate limiting i diagnosi d’errors.

JWT, API-Keys i SSO: què encaixa en la pràctica

Per a integracions sistema-a-sistema són habituals API-Keys o mecanismes Client-Credentials. Per a accessos d’usuari en context empresarial els JWT (JSON Web Token) combinats amb un Identity Provider central (p. ex. OIDC) són sovint pràctics. En entorns SSO també pot ser rellevant SAML 2.0 (un estàndard per a Single Sign-on, normalment entre portal/gateway i Identity Provider).

Independentment del mètode cal definir:

• Rotació de claus i certificats (com es renoven les signatures?)
• Rols/Scopes (quins permisos s’apliquen a cada endpoint?)
• Multitenancy (com s’imposa correctament l’assignació de tenant?)
• Audit-Logging (qui va provocar quina acció de negoci i quan?)

Validació d’entrada, CORS i Rate Limiting

La validació d’entrada ha de ser multinivell: sintàctica (tipus de dades, estructura JSON), funcional (rangs de valors, transicions d’estat) i rellevant per la seguretat (noms de fitxers, rutes, headers). Per a clients de navegador CORS és important (quins origins i headers estan permesos). CORS s’ha de configurar de forma restrictiva. Rate Limiting protegeix contra abús i pics de càrrega; sovint s’implementa al reverse proxy i es complementa amb límits en el servidor (mida màxima del body, timeouts, concurrència limitada).

FireDAC i l’accés a la base de dades: l’estabilitat ve per regles

En backends REST l’accés a la base de dades sovint determina latència i estabilitat. FireDAC proporciona les capacitats tècniques, però la seguretat operativa s’aconsegueix amb guardrails.

Gestió de connexions i concurrència

Un error clàssic és compartir una connexió de base de dades global que s’usa de forma paral·lela per diverses requests. En un REST-Server amb execució paral·lela (threads/workers) cal deixar clar quins objectes són thread-safe i quins no. A la pràctica això vol dir: gestionar connexions i objectes de consulta per request o per unit-of-work de manera neta, o utilitzar pooling controlat segons el model de servidor. Això redueix deadlocks, errors esporàdics i problemes difícils de reproduir.

Transaccions alineades amb els casos d’ús

Les transaccions pertanyen al domini: un cas d’ús decideix què ha de ser atòmic. Sovint “una request = una transacció” és una regla raonable, però no sempre. Els endpoints només de lectura normalment no necessiten una transacció explícita, mentre que processos d’escriptura que modifiquen diverses taules han de garantir coherència. Amb integracions externes (ERP, DMS, webhooks) les transaccions distribuïdes solen ser poc realistes; aquí ajuden ordres clarament definides i lògica de compensació (com es rectifica un èxit parcial?).

Timeouts, backpressure i fallada controlada

Sense timeouts les peticions, els threads i les connexions a BD s’encallen. Per això cal establir timeouts a nivell HTTP i DB. A més és important el backpressure: limitar la concurrència i la longitud de cues perquè el sistema, sota càrrega, respongui controladament amb 503 (Service Unavailable) en lloc d’esgotar recursos i caure del tot. Per a l’operació és preferible un patró d’error ràpid i clar que bloquejos de minuts.

Payloads, DTOs i compatibilitat a llarg termini

JSON és l’estàndard, però la interoperabilitat depèn dels detalls: format de data/hora, zones horàries, valors null, representació de decimals, noms de camps i encoding. Definiu un estàndard (p. ex. ISO-8601 en UTC) i apliqueu-lo de forma coherent.

DTOs en comptes de publicar estructures de base de dades

DTOs (Data Transfer Objects) són models de dades pensats per a l’intercanvi. No haurien de reflectir simplement les taules de la base de dades. Això evita que canvis interns d’esquema trenquin immediatament l’API. A més, permet controlar quins camps interns no surten a l’exterior (p. ex. flags, columnes d’auditoria) i facilita el refactoring intern sense posar en perill les integracions.

Considerar idempotència i reintents

En xarxes d’empresa timeouts i reintents són habituals. Definiu quines operacions són idempotents (executar-les diverses vegades produeix el mateix resultat) i com evitar POSTs duplicats, per exemple amb una Idempotency-Key per a certes operacions d’escriptura. Això redueix duplicats, estats inconsistents i incidències de suport.

Documentació i proves: OpenAPI com a base de treball comuna

Una API en B2B rarament és usada només per un equip. OpenAPI (Swagger) funciona com a llenguatge comú perquè les especificacions són automatitzables: generació de clients, mocking, contract-tests i comparació entre versions. Encara que l’stack Delphi no generi tot automàticament, val la pena mantenir una especificació com a artifact central.

Cobertura de proves pragmàtica que redueix costos d’operació

Una estructura de proves raonable per serveis REST acostuma a tenir tres nivells:

• Unit-Tests per la lògica de domini (sense HTTP, sense BD)
• Integrationtests per l’accés a dades i comportament de transaccions (amb BD de proves i dades inicials reproductibles)
• API/Contract-Tests contra un servei en execució (codis d’estat, auth, formats d’error, versionat)

Per a administradors i equips d’operació és fonamental: les proves han de ser reproductibles i no dependre de l’entorn del desenvolupador. Com més s’assembli l’entorn de proves al desplegament final, menor serà el risc de sorpreses després d’actualitzacions.

Desplegament i operació: Windows-Service, Linux-Service, contenidors

Un servidor REST es considera pràcticament “llest” només quan es pot operar amb estabilitat: comportament de start/stop, rotació de logs, actualitzacions, permisos, obertura de ports, certificats, monitoring i opcions clares de rollback.

Windows- i Linux-Services: models d’operació provats

Sota Windows el funcionament com a Windows- und Linux-Services sovint és l’opció més senzilla perquè ja existeixen mecanismes per a tipus d’inici, recuperació, permisos i monitoring. A Linux sovint s’utilitza un servei systemd (systemd és el gestor de serveis estàndard) que controla polítiques de reinici, integració de logs i ordre d’inici. Per ambdós mons val: un reverse proxy al davant simplifica TLS, polítiques de headers, rate limits i routing.

Contenidors: reproductibilitat, però només amb separació neta de l’estat

Els contenidors poden unificar desplegaments i accelerar rollouts. La condició és una separació clara de l’estat: base de dades externa, fitxers en volumes, secrets mitigats per un Secret-Management. Sense aquesta disciplina es generen estats mixtos difícils de mantenir, que afloren en incidents o en escenaris de restauració.

Configuració: rastrejable, separada per entorns, sense secrets al repo

Un model de configuració coherent ajuda: ajustos separats per Dev/Test/Prod, definició central de nivells de log, dades de connexió a BD, timeouts, origins permesos i claus de tokens. Les dades sensibles no han d’estar al repo de codi font. Per a auditories i operació és important que els canvis de configuració siguin rastrejables i es puguin desplegar de forma controlada.

Observability: logs, mètriques i tracing com a requisit d’operació

Quan les integracions fallen, l’equip d’operació necessita respostes: quins endpoints estan afectats, des de quan, amb quina taxa d’errors i quina dependència és lenta? Sense observability cada incidència esdevé una investigació manual.

Logging estructurat i Correlation-IDs

El logging estructurat (clau/valor o JSON) permet anàlisis amb eines i facilita filtrar per endpoint, tenant, codi d’error o Correlation-ID. Cada request hauria de rebre una Correlation-ID que també es retorni en el header de la resposta. Les dades sensibles com contrasenyes, tokens o contingut personal no s’han d’enregistrar; aquí ajuden l’enmascarament, hashing o logs de debug restringits a entorns tancats.

Mètriques per capacitat i estabilitat

Mètriques comprovades són la taxa de requests, latències (p.ex. p95/p99), taxes d’error per endpoint, temps a la BD, nombre de workers/threads actius, càrrega de connexions i longituds de cues. Aquests valors són la base per a la planificació de capacitat i ajuden a detectar problemes lents (índexs que falten, noves dependències, rutes de consulta subòptimes).

Camí de modernització: REST com a frontera estable per sistemes Delphi heretats

En moltes instal·lacions Delphi l’API REST no és l’estat final sinó un element de modernització i estabilitat. Un enfocament provat i de baix risc és progressiu:

1. Prioritzar casos d’ús: Quines funcions han d’estar disponibles externament (dades mestres, canvis d’estat, accés a documents, aprovacions)?
2. Definir estàndards d’API: Auth, format d’errors, versionat, logging, timeouts, rate limits, OpenAPI.
3. Extreure la domnia: Estructurar la lògica de negoci perquè no estigui lligada a la UI o a endpoints concrets.
4. Consolidar l’accés a dades: regles FireDAC, concepte de transacció, línies base de rendiment, polítiques de consulta.
5. Canviar els consumers de manera gradual: escriptori, portals i altres serveis consumeixen l’API; els accès directes a BD es van reduint.

El resultat és un sistema que es pot evolucionar per fases: els mòduls es poden renovar sense que els canvis s’escampin incontroladament a tots els clients.

Errades típiques en projectes B2B-REST

Alguns patrons erronis es repeteixen i es poden evitar amb regles clares:

• Formats d’error incoherents: el suport i la integració es tornen innecessàriament difícils. Solució: objecte d’error estandarditzat amb codis d’error estables.
• Seguretat com a afegit: rols, multitenancy i auditoria s’afegeixen “més tard”. Solució: planificar-ho com a estructura fonamental, no improvisar per endpoint.
• No posar límits: l’absència de límits de body, timeouts i concurrència provoca fallades sota càrrega. Solució: reverse proxy més backpressure al servidor.
• Base de dades massa lligada a l’API: cada canvi d’esquema trenca els consumers. Solució: DTOs i casos d’ús ben definits.
• Poca observabilitat: els problemes no són mesurables. Solució: Correlation-IDs, logs estructurats, mètriques clau.

Conclusió: REST amb Delphi implica responsabilitat sobre la interfície i l’operació

Desenvolupar un REST-Server amb Delphi té èxit de forma sostenible en entorns empresarials quan l’arquitectura i l’operació es planifiquen conjuntament des del principi. L’elecció del framework (WebBroker, Horse, RAD Server o una migració des de DataSnap) és rellevant, però no és l’apalancament més gran. El que marca la diferència són estàndards clars per al disseny d’API, autenticació, tractament d’errors, versionat, accés a dades FireDAC, timeouts així com observability i desplegament com a Windows- o Windows- und Linux-Services. Així una interfície esdevé un bloc d’integració estable que facilita la modernització en comptes d’impedir-la.

En l’àmbit funcional també juguen un paper important la Delphi REST-API i la Delphi REST-API i REST-Server quan integracions, fluxos de dades i evolució han de funcionar de forma ordenada.

Projekt oder Modernisierungsvorhaben mit Net-Base besprechen.