Moltes empreses disposen de software existent, validat funcionalment, que representa els processos clau amb fiabilitat, però que és difícil d’integrar. Tan aviat com cal connectar un portal de clients, un nou DMS/CRM, informes BI, partners EDI o processos mòbils, queda clar: sense interfaces netes cada integració serà costosa, propensa a errors i difícil de mantenir. Precisament aquí entra en joc la qüestió d’incorporar una API REST per a software existent: creen un accés controlat i documentat a funcions i dades sense haver de redissenyar l’aplicació per complet.
Aquest article descriu com planificar i introduir una interfície REST (REST = „Representational State Transfer“, un estil estès per a APIs basades en HTTP) per a aplicacions existents. L’enfocament no és detall d’un framework, sinó operació, dades, seguretat, versionat, rutes de migració i la pràctica diària de direcció TI, administració i responsables tècnics de projecte.
Per què una API REST sovint és el pas de modernització més raonable per a software existent
Una API afegida posteriorment és sovint la unitat mínima d’una modernització real amb benefici tangible. Permet construir noves capes d’interfície (portal web, informes, aplicacions mòbils) sense haver d’intervenir immediatament en la lògica de negoci madura del nucli. Al mateix temps, redueix els accessos directes a la base de dades per part de sistemes tercers —un punt típic de risc per a estabilitat i seguretat en entorns legacy.
Motius pràctics típics:
- Integració en lloc d’illes aïllades: ERP, CRM, DMS, proveïdors d’identitat, reporting i interfícies de partners necessiten un contracte estable per a dades i funcions.
- Desacoblament de la UI i la lògica de negoci: si la capa d’interfície envelleix, es pot substituir mentre la lògica continua exposada via API.
- Accés controlat: en lloc de “SQL des de fora”, s’obté autenticació, rols/ უფლება (autorizació), auditoria i limitació de taxa centralitzats.
- Migració gradual: àrees funcionals es poden fer compatibles amb l’API de manera incremental i posteriorment refactoritzar o migrar cap a serveis.
REST-API per a software existent: avaluar la situació de manera realista
Abans de dissenyar una API val la pena una anàlisi freda de l’estat actual. “Software existent” sol significar: creixement històric, molts casos especials, llarga vida en producció i sovint una estreta relació entre UI, base de dades i lògica de negoci. Una API REST fa visibles aquestes connexions —i això és positiu si s’aborda d’una manera estructurada.
Quins tipus d’integració existeixen ja?
En molts entorns ja hi ha “interfícies”, però sovint informals:
- Accessos directes a la base de dades per informes, exportacions Excel, scripts o sistemes externs
- Intercanvi basat en fitxers (CSV, XML, carpetes PDF, “drop-folder”)
- Intercanvi per FTP/SFTP, processos basats en correu electrònic
- RPC/COM, SOAP, protocols propietaris TCP/IP o cues de missatges
Aquests mecanismes no són intrínsecament incorrectes. Es tornen problemàtics quan no existeixen responsabilitats clares, versionat o límits de seguretat. Una API REST no substitueix necessàriament tot d’un cop, però estableix un accés vinculant per a noves necessitats.
Quines parts de la lògica de negoci són “aptes per API”?
Un error comú és pensar: API = “donar dades”. En software empresarial gairebé sempre es tracta de transaccions (operacions de negoci com “crear comanda”, “registrar entrada de mercaderies”, “assignar permisos”). Una API robusta modela primer els processos i després les simples consultes de dades.
Per a la priorització, s’ha demostrat útil:
- Alto impacte d’integració: funcions que impliquen diversos sistemes (p. ex. dades mestres, canvis d’estat, enllaç de documents).
- Elevat esforç manual: ruptures de procés i exportacions/importacions recurrents.
- Alta rellevància per la seguretat: àrees on avui “qui té drets de BD” veu massa informació.
Decisions d’arquitectura: API dins l’aplicació existent o davant d’ella?
En afegir una interfície REST hi ha dos patrons bàsics, que també es poden combinar:
1) API com a component integrat de l’aplicació existent
Aquí el servidor REST s’executa “proper” a la lògica de negoci, sovint en el mateix deployment (p. ex. com a Windows- i Linux-serveis, Linux-daemon o com a mòdul dins del procés servidor existent). Avantatge: accés directe a regles de negoci, menys duplicació de lògica. Risc: el deployment i la estabilitat del sistema existent han de suportar la càrrega de l’API i els requisits de seguretat.
2) Façana d’API com a sistema separat (Facade/Adapter)
L’API s’executa com un servei independent que parla amb el software existent per canals definits (base de dades amb vistes/Stored Procedures clares, interfícies existents, missatgeria o adaptadors específics). Avantatge: operació neta, escalabilitat i controls de seguretat independents. Risc: més treball arquitectònic; la frontera entre “façana” i “lògica de negoci” ha d’estar ben traçada per evitar l’aparició de lògica sombra.
API-Gateway, sí o no?
Un API-Gateway és una capa frontal que centralitza temes transversals: routing, autenticació, limitació de taxa, terminació TLS, correlació de logs. Per a una única API interna no és imprescindible, però pot ser útil des de bon començament si s’espera tenir diverses APIs o accés per partners externs. Important: un gateway no substitueix la qualitat interna: versionat, comportament d’errors i contractes de dades han d’estar ben definits de totes maneres.
Dades i contractes: per què el model de dades de l’API no hauria de ser 1:1 amb l’esquema de BD
Una API REST és un contracte. Qui l’utilitza construeix processos de negoci, automatitzacions i informes sobre ella. Per això l’objectiu principal de disseny és la estabilitat —no “posar-ho tot disponible”. Un error comú és exposar les taules de la base de dades directament. Això acobla els consumidors a estructures internes i converteix qualsevol canvi de BD en una ruptura d’integració.
Introduir DTOs, recursos i agregacions de manera comprensible
En les APIs s’utilitza sovint DTOs (“Data Transfer Objects”, és a dir, estructures de dades transferides). Per a operació TI i responsables de projecte, la idea clau és: els objectes API estan tallats conscientment. Poden agregar diverses taules, reanomenar camps, ocultar claus internes i entregar només el que el procés necessita.
Bones pràctiques en entorns amb software existent:
- Introduir IDs externs que siguin estables (en lloc d’exposar claus tècniques internes).
- Nomenclatura semàntica dels camps (terminologia de domini, no noms de taula).
- Proporcionar endpoints agregats que cobreixin consultes típiques d’UI o de processos, per evitar 10 crides REST per una sola vista.
Lectura vs. escriptura: delimitar clarament les fronteres transaccionals
Per a consultes (GET) sovint es pot entregar valor ràpidament, per a portals o reporting. Les operacions d’escriptura (POST/PUT/PATCH/DELETE) són més exigents perquè hi intervenen validacions, permisos, efectes col·laterals i seguretat transaccional. Planifiqueu per això:
- Primer endpoints de lectura per a les vistes més importants
- Després operacions d’escriptura seleccionades com a comandes de domini (“posar estat”, “afegir posició”) en comptes de “desar registre” genèric
Seguretat i accés: autenticació, autorització i registre d’esdeveniments
Una API afegida és un nou canal d’accés. Això modifica el model de riscos i les responsabilitats. Tres àmbits han d’estar planificats des del principi: identitat, drets i traçabilitat.
Autenticació: qui fa la crida?
En entorns empresarials és habitual integrar l’API amb un sistema d’identitat central. Elements freqüents: OAuth 2.0 (delegació d’accés via tokens) i OpenID Connect (capa d’identitat sobre això). També és comú SAML 2.0, especialment per a Single Sign-On en portals corporatius. Important: l’API hauria de validar tokens i no construir un silo de comptes/contrassenyes propi si hi ha un Identity-Provider disponible.
Autorizació: què pot fer qui crida?
Autorizació és la comprovació de rols, permisos i abast de client/tenant. Requeriments típics en software existent:
- Aïllament de tenants (Tenant-Isolation): dades i operacions han d’estar estrictament separades.
- Permisos basats en rols (RBAC): p. ex. lectura, registració, aprovació, administració.
- Regles per objecte: “només pot veure entrades pròpies” o “només la unitat X pot accedir”.
Una API robusta fa complir aquestes regles al servidor —independentment de si qui crida és un portal, un script o un partner.
Audit Logging: què ha passat i quan?
Especialment per a operacions d’escriptura l’audit-logging (registres revisions) és central. Com a mínim cal registrar: hora, identitat que ha cridat, endpoint, ID d’objecte rellevant, resultat (exitós/fallit) i una correlació-ID per rastrejar entre sistemes. Això no és un “nice-to-have”: redueix temps de suport i és rellevant per a compliance i controls interns en molts sectors.
Operació i fiabilitat: què han d’assegurar els administradors des del començament
Les APIs es tracten en el dia a dia com a infraestructura. Si fallen o són lentes, els processos s’aturen. Per això no convé deixar per al final l’operació i l’observabilitat (mètriques/logs/traces).
Monitoring, mètriques i alertes sensates
Per a una operació estable no n’hi ha prou amb “funciona” i “resposta arriba”. Mètriques mínimes recomanades:
- Latença per endpoint (p. ex. p95/p99) per detectar valors atípics
- Taxa d’errors (HTTP 4xx/5xx), separada per endpoints
- Throughput (peticions per minut) per entendre patrons de càrrega
- Dependències BD/Backend: temps d’espera, timeouts, utilització de pool
Les alarmes no haurien de reaccionar a pics puntuals, sinó a tendències i fallades sostenides. Això evita la “fatiga d’alertes” en el personal de guàrdia.
Rate Limiting i protecció contra mal ús
La limitació de taxa restringeix les peticions per unitat de temps per protegir el software existent contra sobrecàrrega —incloent clients benintencionats però ineficients. Complementàriament són útils: timeouts de petició, mides màximes de payload i missatges d’error clars perquè els clients puguin corregir el seu comportament.
Comportament d’errors i idempotència
Idempotència vol dir: una petició es pot enviar diverses vegades sense efectes secundaris indesitjats (p. ex. duplicats). Això és important perquè xarxes i clients poden provocar reintents. Per a administradors i decisors el benefici és clar: menys duplicitats, menys correccions manuals, processos més robustos. Planifiqueu per a operacions d’escriptura crítiques mecanismes com Idempotency-Keys o identificadors únics d’operació.
Deploy sense interrupcions de servei
Quan una API està en producció, cada canvi és un risc potencial. Principis provats:
- Compatibilitat cap enrere: afegir camps és generalment segur; eliminar camps o canviar significats és crític.
- Blue/Green o Rolling Deployments: dues versions en paral·lel o substitucions progressives per evitar temps d’inactivitat.
- Planificar migracions de base de dades per separat: canvis d’esquema executats de manera que versions antigues i noves de l’API siguin compatibles durant un període.
Versionat i cicle de vida: com mantenir els canvis controlats
El versionat d’API no és una qüestió teòrica d’arquitectura, sinó una eina per evolucionar sense crisis permanents. En entorns amb software existent normalment hi ha diversos consumidors: portal intern, reporting, partners, automatismes i potser clients externs. Canviar-los tots a la vegada rarament és realista.
Quina estratègia de versionat és pràctica?
És habitual versionar a la URL (p. ex. /v1/…) o via headers. Per a organització i operació la versionat a la URL sovint és més senzill, perquè és visible en logs, gateways i monitoring. El més important no és el “com” sinó la conseqüència: una versió té un període de suport definit i els breaking changes s’introdueixen de forma controlada.
Política de deprecació i comunicació
Definiu des d’un inici una deprecation-policy: quant de temps roman v1 quan apareix v2? Com s’informa els consumidors? Fins i tot internament això és crucial; si no, les versions antigues es queden indefinidament en funcionament i augmenten la càrrega de manteniment i risc de seguretat.
Modernitzar l’accés a dades sense reescriure-ho tot
En afegir una API REST els equips es topen sovint amb deute tècnic en l’accés a dades: estils SQL mixtos, límits de transacció mancants, accessos directes a taules des de molts punts. L’objectiu no ha de ser la perfecció, sinó la capsulació: l’API ha de proporcionar una via definida cap a la persistència.
Capa de servei i responsabilitats clares
Una capa de servei concentra la lògica de negoci i les regles per a les crides API: validació, permisos, transaccions, efectes secundaris. Això redueix el risc que cada endpoint “cuini la seva pròpia sopa”. Per a la operació i el manteniment és rellevant perquè els patrons d’error es tornen més consistents i els canvis tenen menys efectes col·laterals.
Quan la base de dades és ella mateixa legacy
Moltes aplicacions depenen de sistemes de base de dades o drivers antics. L’API pot ser la palanca per estabilitzar l’accés a dades gradualment: drivers nous, pools de connexions clars, codificació de caràcters coherent (p. ex. Unicode), tractament net de valors de data/temps. Decisiu: mesurar i estabilitzar abans de refactoritzar. Una API que “de vegades” retorna marques de temps incorrectes ràpidament perd credibilitat.
Trampes típiques en l’afegit d’una API i com evitar-les
Molts problemes no provenen de REST en si, sinó d’objectius poc clars i manca de planificació operativa. Els punts següents són especialment comuns en integracions amb software existent:
1) “Simplement exposem taules”
Això porta a acoblament estret, fugues de dades incontrolades i versionat difícil. Millor: recursos i operacions de domini, DTOs i IDs externs estables.
2) Responsabilitats poc clares sobre la qualitat de dades
Si diversos sistemes escriuen via l’API cal establir on resideix la “Single Source of Truth”. Altrament apareixen conflictes, duplicats o estats inconsistents. Definiu per cada àrea de dades: qui pot crear, qui pot modificar, qui només pot llegir.
3) Falta d’estratègia de càrrega i timeouts
Una API pot generar càrrega nova: portals que fan polling, BI que extreu volums grans, partners que provoquen pics. Sense timeouts, límits i endpoints adequats es posa pressió innecessària a la base de dades i la lògica de negoci. Planifiqueu perfils de càrrega abans que el primer consumidor extern entri en producció.
4) Seguretat només “després del proof of concept”
En context d’API sovint és més car afegir autenticació, rols i auditoria a posteriori que fer-ho bé des del principi. Encara que s’iniciï de manera interna, planifiqueu la seguretat de manera que l’API pugui exposar-se externament sense haver de girar l’arquitectura.
Un pla de projecte pragmàtic en sis passos
Per evitar que la incorporació quedi només en concepte, ajuda un enfoc que generi èxits ràpids i alhora protegeixi l’operació:
- Clarificar objectius i consumidors: portal, reporting, partners, automatismes. Quins processos van primer?
- Segmentar dominis: dades mestres, operacions, documents, permisos. No fer “una API gran” sense estructura.
- Establir una baseline de seguretat: integració d’identitat, rols, lògica de tenants, esdeveniments d’auditoria, TLS.
- Entregar Read-First: els endpoints de lectura més importants amb DTOs estables, paginació/filtrat i errors explicables.
- Operacions d’escriptura com a comandes: poques transaccions clares amb idempotència i validació robusta.
- Estandarditzar l’operació: monitoring, correlació de logs, estratègia de deployment, versionat i política de deprecació.
Així es crea una API que realment s’utilitza, en lloc de quedar com una “ruta secundària” tècnica.
Com una API prepara el camí per a la modernització
Afegir una API REST rarament és l’objectiu final. Sovint és el punt de partida per migrar el software existent cap a una arquitectura més robusta: separar mòduls, substituir accessos a dades obsolets, establir noves interfícies d’usuari i externalitzar processos en background com a serveis. L’avantatge clau: l’API estableix un contracte d’integració al qual poden referir-se altres mesures.
Quan més endavant es refactoritzi o migri internament, els consumidors poden seguir treballant a través de l’API sempre que el contracte es mantingui estable. Això redueix el risc del projecte i evita canvis del tipus “big bang”.
Conclusió: una API REST afegida posteriorment és un projecte d’operació, no només una característica de desenvolupament
Una interfície REST per a software existent té èxit quan modela correctament els processos, compleix requisits de seguretat i és gestionable en producció. El major benefici arriba quan l’API no es veu com un canal d’exportació, sinó com un contracte clar entre sistemes: versionat, documentat, monitoritzat i amb responsabilitats definides per dades i drets.
Si voleu incorporar una REST-API per a software existent i voleu integrar des d’un inici arquitectura, seguretat i operació de manera ordenada, parlem de la vostra situació i d’un pla d’implantació realista:
En l’àmbit funcional també tenen un paper important l’autenticació i l’autorizació, perquè integracions, fluxos de dades i evolució funcionin de manera coordinada.
Parleu del projecte o del vostre procés de modernització amb Net-Base.