Mnoge kompanije posjeduju funkcionalno provjereni postojeći softver koji pouzdano modelira ključne procese – ali je ograničeno integrabilan. Čim se želi povezati klijentski portal, novo DMS/CRM, BI-izvještaji, EDI-partneri ili mobilni tokovi, brzo postane jasno: bez čistih sučelja svaka integracija postaje skupa, sklona greškama i otežano održiva. Upravo tu leži tema REST-API za naknadno opremanje postojećeg softvera: on osigurava kontroliran, dokumentiran pristup funkcijama i podacima, bez potrebe za kompletnom reinženjeringom aplikacije.
Ovaj članak opisuje kako planirati i uvesti REST-sučelje (REST = „Representational State Transfer“, uobičajeni stil za HTTP-bazirane API-je) za postojeće aplikacije. Fokus nije na detaljima frameworka, već na operacijama, podacima, sigurnosti, verzioniranju, migracijskim putevima i svakodnevnim potrebama IT-u, administraciji i tehničkim voditeljima projekata.
Zašto je REST-API za postojeći softver često najrazumniji korak modernizacije
Naknadno dodana API-je često predstavljaju najmanju jedinicu stvarne modernizacije s opipljivom vrijednošću. Omogućavaju izgradnju novih korisničkih slojeva (web-portal, reporting, mobilne aplikacije) bez neposrednog diranja u postojeću poslovnu logiku. Istovremeno smanjuju izravne pristupe bazi podataka od trećih strana – tipičnu točku rizika za stabilnost i sigurnost u legacy okruženjima.
Tipični razlozi iz prakse:
- Integracija umjesto otoka sustava: ERP, CRM, DMS, Identity-Provider, reporting i partnerska sučelja trebaju stabilan ugovor za podatke i funkcije.
- Razdvajanje UI i poslovne logike: Kada se sučelje zastari, može se zamijeniti, dok se logika putem API-ja dalje koristi.
- Kontroliran pristup: Umjesto „SQL izvana“ dobivate autentifikaciju, uloge/ ovlaštenja (autorizacija), evidentiranje i ograničenja učestalosti na jednom mjestu.
- Postepena migracija: Funkcionalne cjeline se mogu jednu po jednu učiniti API-prikladnima i kasnije interno modernizirati ili prevesti u servise.
REST-API za postojeći softver: realistična procjena početnog stanja
Prije dizajniranja API-ja vrijedi napraviti trezvenu inventuru. „Postojeći softver“ obično znači: historijski rast, mnogi specijalni slučajevi, dug vijek trajanja, često tesna povezanost UI, baze podataka i poslovne logike. REST-API razotkrit će te veze – i to je dobro, ako se pristupi strukturirano.
Koje vrste integracija već postoje?
U mnogim okruženjima već postoje „sučelja“, ali najčešće neformalno:
- Direktni pristupi bazi podataka putem izvještaja, Excel-eksporta, skripti ili tuđih sustava
- Prijenosi datoteka (CSV, XML, PDF-mape, „drop-folder“)
- FTP/SFTP razmjena, procesi temeljeni na e-pošti
- RPC/COM, SOAP, proprietarni TCP/IP-protokoli ili message-queue sustavi
Ovi mehanizmi nisu nužno pogrešni. Problem nastaje kad ne postoje jasne odgovornosti, verzioniranje i sigurnosne granice. REST-API često ne zamjenjuje sve odjednom, ali osigurava obavezan ulaz za nove zahtjeve.
Koji dijelovi poslovne logike su „pogodni za API“?
Česta zabluda: API = „izvoz podataka“. U poslovnom softveru gotovo uvijek je riječ o transakcijama (poslovni događaji poput „kreiraj nalog“, „knjiži prijem robe“, „dodijeli privilegiju“). Robustan API stoga prvo modelira događaje, a tek potom čiste upite podataka.
Za prioritizaciju se pokazalo korisnim:
- Veliki integracijski utjecaj: funkcije koje zahtijevaju više sustava (npr. osnovni podaci, promjene statusa, vezivanje dokumenata).
- Velik ručni napor: medijski prekidi i ponavljajući export/import poslovi.
- Visoka sigurnosna važnost: područja gdje danas „svatko s DB-pravima“ vidi previše.
Arhitektonske odluke: API ispred postojećeg softvera ili ugrađen u aplikaciju?
Pri naknadnom uvođenju REST-sučelja postoje dva osnovna obrasca koja se mogu i kombinirati:
1) API kao integrirana komponenta postojeće aplikacije
Ovdje REST-server radi „blizu“ poslovne logike, često u istom deploymentu (npr. kao Windows- und Linux-Services, Linux-Daemon ili kao modul u postojećem server-procesu). Prednost: direktan pristup poslovnim pravilima, manje duplicirane logike. Rizik: deployment i stabilnost postojeće aplikacije moraju podnijeti API-opterećenje i sigurnosne zahtjeve.
2) API-fasada kao zaseban sustav (Facade/Adapter)
API se pokreće kao samostalna usluga koja komunicira s postojećom aplikacijom preko definiranih kanala (baza s jasnim view-ovima/stored procedurama, postojeća sučelja, messaging ili ciljane adaptere). Prednost: uredniji operativni rad, neovisna skalabilnost i sigurnosne kontrole. Rizik: više arhitektonskog posla; potrebno je strogo povući granicu između „fasade“ i „poslovne logike“ kako ne bi nastala sjenovita logika.
API-Gateway — da ili ne?
API-gateway je predložena komponenta koja centralno rješava poprečne teme: routing, autentifikaciju, ograničenje učestalosti, TLS-terminaciju, korelaciju logova. Za jednu internu API nije nužan, ali može biti koristan rano ako se očekuje više API-ja ili ako će pristupati vanjski partneri. Važno je da gateway ne zamjenjuje internu kvalitetu: verzioniranje, ponašanje u greškama i ugovori o podacima moraju i dalje biti uredni.
Podaci i ugovori: Zašto API-datamodel ne bi trebao biti 1:1 s DB-shemom
REST-API je ugovor. Oni koji ga koriste grade na njemu poslovne procese, automatizacije i analitiku. Stoga je najvažniji cilj dizajna stabilnost – ne „omogućiti sve“. Česta pogreška je izlaganje tablica baze prema van. To veže potrošače na interne strukture i svaka promjena DB-a postaje integracijski prekid.
DTO-i, resursi i agregacije – jasno uvesti
U API-jima se često radi s DTO-ima („Data Transfer Objects“, odnosno strukture za prijenos podataka). Ključna poruka za IT-drift i voditelje projekata: API-objekti su svjesno odrezani. Mogu objedinjavati više tablica, preimenovati polja, sakriti interne ključeve i isporučiti samo ono što proces treba.
Dobra praksa u postojećim okruženjima:
- Uvesti vanjske ID-e koji ostaju stabilni (umjesto izlaganja internih tehničkih ključeva).
- Semantički imenovati polja (prema domeni, ne prema tablici).
- Pružiti agregirane endpoint-e koji pokrivaju tipične UI- ili procesne upite, kako ne bi bilo potrebno 10 poziva.
Čitanje vs. pisanje: jasno povući transakcijske granice
Za upite (GET) često možete brzo isporučiti dodanu vrijednost, npr. za portale ili reporting. Operacije pisanja (POST/PUT/PATCH/DELETE) su zahtjevnije zbog validacije, autorizacije, nuspojava i transakcijske sigurnosti. Planirajte stoga:
- Prvo read-only endpoint-e za najvažnije poglede
- Zatim odabrane pisane operacije kao jasne poslovne naredbe („postavi status“, „dodaj stavku“) umjesto „spremi zapis“
Sigurnost i pristup: autentifikacija, autorizacija i evidentiranje
Naknadna API predstavlja novi kanal pristupa. Time se mijenja model prijetnji i odgovornosti. Tri područja moraju biti planirana od početka: identitet, prava i moć praćenja.
Autentifikacija: tko je pozivatelj?
U poslovnim okruženjima uobičajeno je povezati API s centralnim identity-sistemom. Česti dijelovi rješenja su OAuth 2.0 (delegiranje pristupa putem tokena) i OpenID Connect (sloj za identitet iznad toga). Također je raširen SAML 2.0, posebno za single sign-on u poslovnim portalima. Važno: API bi trebao moći provjeravati tokene i ne graditi vlastiti korisničko-loznički silo ako postoji identity-provider.
Autorizacija: što pozivatelj smije raditi?
Autorizacija znači provjeru uloga, prava i konteksta najamnika. Tipični zahtjevi u postojećem softveru:
- Odvajanje klijenata (Tenant-Isolation): podaci i operacije moraju biti strogo odvojeni.
- Upravljanje pravima po ulogama (RBAC): npr. čitanje, knjiženje, odobravanje, administracija.
- Pravila vezana za objekte: „može gledati samo vlastite tickete“ ili „samo troškovno mjesto X“.
Robustan API nametne ova pravila server-side – neovisno o tome dolazi li poziv iz portala, skripte ili partnera.
Audit logging: što se i kada dogodilo?
Posebno za pisane operacije je audit-logging (revidirajuće ili barem pratljivo zapisivanje promjena) centralan. Minimalno treba zabilježiti: vrijeme, pozivateljski identitet, endpoint, relevantni ID objekta, rezultat (uspjeh/neuspjeh) i korelacijsku ID za praćenje preko sustava. To nije „nice-to-have“: smanjuje vrijeme podrške i u mnogim branšama je važno za usklađenost i interne kontrole.
Operacije i pouzdanost: što administratori trebaju rano osigurati
API-je u svakodnevici treba tretirati kao infrastrukturu. Ako izostanu ili su spori, procesi stoje. Zato se isplati ne ostavljati operativnost i observabilnost (metrike/logovi/traces) za kraj.
Monitoring, metričke vrijednosti i smisleni alarmi
Za stabilan rad „radi“ i „odgovara“ nisu dovoljni. Smisleni minimalni metrički set:
- Latencija po endpointu (npr. p95/p99), za detekciju odstupanja
- Stope grešaka (HTTP 4xx/5xx), odvojeno po endpointima
- Protok (requests po minuti), za razumijevanje obrazaca opterećenja
- Ovisnosti o DB-/backendu: vremena čekanja, timeout-i, iskorištenost poola
Alarmi ne bi trebali reagirati na jedinstvene pikove, već na trendove i trajne degradacije. Tako se sprječava „utmicanje alarma“ u pripravnosti.
Rate limiting i zaštita od zloupotrebe
Ograničenje broja zahtjeva štiti postojeći softver od preopterećenja – i od „dobronamjernih“ ali neučinkovitih klijenata. Uz to su korisni: timeout-i po zahtjevu, maksimalne veličine payload-a i jasne poruke o greškama, kako bi klijenti mogli prilagoditi ponašanje.
Ponašanje pri greškama i idempotentnost
Idempotentnost znači: zahtjev se može poslati više puta bez neželjenih nuspojava (npr. dvostruko knjiženje). To je važno jer mreže i klijenti mogu izazvati ponavljanja. Za administratore i donosioce odluka jasna je posljedica: manje duplikata, manje ručnih ispravki, robusniji procesi. Za kritične pisane operacije planirajte mehanizme poput Idempotency-Keys ili jedinstvenih identifikatora transakcija.
Deployment bez prekida operacija
Kada je API u proizvodnom korištenju, svaka promjena predstavlja potencijalni rizik. Dokazane prakse:
- Backward Compatibility: dodavanje novih polja je obično bezopasno; uklanjanje polja ili promjena značenja je kritično.
- Blue/Green ili Rolling Deployments: dvije verzije paralelno ili postupna zamjena, za izbjegavanje downtime-a.
- Odvojeno planiranje migracija baze podataka: promjene sheme izvoditi tako da stare i nove API-verzije neko vrijeme ostanu kompatibilne.
Verzioniranje i životni ciklus: kako učiniti promjene upravljivima
Verzioniranje API-ja nije teorijska arhitektonska tema već alat za razvoj bez trajne krize. U okruženjima s postojećim softverom obično imate više potrošača: interni portal, reporting, partnerska sučelja, automatizacije, možda vanjske korisnike. Svi ih istovremeno prebaciti rijetko je realno.
Koja strategija verzioniranja je praktična?
Uobičajeno se verzije stavljaju u URL (npr. /v1/…) ili preko header-a. Za organizaciju i operacije URL-verzioniranje je često jednostavnije jer je odmah vidljivo u logovima, gateway-ima i monitoringu. Bitnije je manje „kako“, a više posljedica: verzija ima definirano razdoblje podrške, a breaking changevi se uvode kontrolirano.
Deprecation-policy i komunikacija
Rano definirajte deprecation-policy: koliko dugo ostaje v1 dostupna kad se pojavi v2? Kako se obavještavaju potrošači? Čak i interno je to odlučujuće, inače stare verzije ostaju trajno u upotrebi i otežavaju održavanje i sigurnost.
Modernizacija pristupa podacima bez potpunog prepisivanja
Pri naknadnom uvođenju REST-API-ja timovi često nalaze tehnički dug oko pristupa podacima: miješani SQL stilovi, nedostatak transakcijskih granica, direktni pristupi tablicama iz više mjesta. Cilj ne mora biti „perfekcija“, već enkapsulacija: API treba pružiti definiran put prema podatkovnom sloju.
Servisni sloj i jasne odgovornosti
Servisni sloj konsolidira poslovnu logiku i pravila za API-pozive: validaciju, autorizaciju, transakcije, nuspojave. To smanjuje rizik da svaki endpoint vodi „svoju malu kuhinju“. Za operacije i održavanje relevantno je da se obrasci grešaka ujednače i da promjene proizvode manje neželjenih nuspojava.
Što ako je sama baza legacy?
Mnoge postojeće aplikacije vezane su za starije baze podataka ili drivere. Tada je API i poluga za postupno stabiliziranje pristupa podacima: novi driveri, jasni connection pool-ovi, konzistentna kodna stranica (npr. Unicode), ispravno rukovanje datumskim/vremenskim vrijednostima. Ključno: prvo mjeriti i stabilizirati, pa onda mijenjati. API koji „povremeno“ isporučuje pogrešne vremenske oznake brzo gubi povjerenje.
Tipične zamke pri naknadnom uvođenju API-ja – i kako ih izbjeći
Mnogi problemi ne proizlaze iz REST kao takvog, već iz nejasnih ciljeva i izostanka planiranja operacija. Sljedeće točke su osobito česte u legacy integracijama:
1) „Samo ćemo izložiti tablice“
To vodi do jake povezanosti, nekontroliranog odliva podataka i teškoće verzioniranja. Bolje: modelirati domenske resurse i događaje, DTO-e i stabilne vanjske ID-e.
2) Nedefinirane odgovornosti za kvalitet podataka
Kad više sustava piše preko API-ja, mora biti jasno gdje je „single source of truth“. Inače nastaju konflikti, dupliciranja ili kontradiktorna stanja. Definirajte za svaki podatkovni domen: tko smije stvarati, tko mijenjati, tko samo čitati?
3) Nedostatak strategije za opterećenje i timeout-e
API može generirati novu opterećenost: portali često pollaju status, BI povlači velike količine podataka, partneri šalju pikove. Bez timeout-a, limit-a i smislenih endpoint-a stvara se nepotreban pritisak na bazu i poslovnu logiku. Planirajte profile opterećenja prije nego što prvi vanjski potrošač krene u produkciju.
4) Sigurnost tek „naknadno nakon PoC-a“
U API-kontekstu je naknadno dodavanje autentifikacije, uloga i audita često skuplje nego čisti početak. Čak i ako u prvoj fazi startate interno: planirajte sigurnost tako da API kasnije može biti izložen vani bez preokreta arhitekture.
Pragmatičan projektni put u šest koraka
Da naknadno opremanje ne zapne u konceptu, pomaže pristup koji donosi brze rezultate, a istovremeno štiti operacije:
- Razjasniti ciljeve i potrošače: portal, reporting, partneri, automatizacije. Koji procesi idu prvi?
- Izrezati domene: osnovni podaci, transakcije, dokumenti, prava. Ne jedna velika API bez strukture.
- Postaviti sigurnosnu osnovu: povezivanje identity-ja, uloge, logika najamna, audit-eventi, TLS.
- Prvo read-first: najvažniji read-endpointi sa stabilnim DTO-ima, paging/filtriranje, razumljive greške.
- Pisane operacije kao komande: malo, jasno definiranih transakcija s idempotencijom i čistom validacijom.
- Standardizirati operacije: monitoring, korelacija logova, deployment-strategija, verzioniranje i deprecacija.
Tako nastaje API koji se stvarno može koristiti, umjesto da ostane tehnička „sporedna cesta“.
Kako API pripremi put modernizaciji
Naknadno uvođenje REST-API-ja rijetko je krajnji cilj. Često je to polazna točka za postupno prevođenje postojećeg softvera u robusniju arhitekturu: jasno odvajanje modula, zamjena zastarjelih pristupa podacima, uvođenje novih sučelja, izdvajanje pozadinskih procesa u servise. Presudna prednost: API stvara stabilan integracijski ugovor oko kojeg se mogu organizirati daljnje mjere.
Kasnije, kad se interno radi refaktor ili migracija, potrošači i dalje rade preko API-ja – sve dok ugovor ostane stabilan. To smanjuje rizik projekta i sprječava „Big Bang“ prebacivanje.
Zaključak: Naknadno uveden REST-API je operativni projekt, a ne samo razvojna značajka
REST-sučelje za postojeći softver uspješno je kada čisto modelira poslovne događaje, zadovoljava sigurnosne zahtjeve i može se upravljati u radu. Najveću vrijednost daje činjenica da se API ne doživljava kao izvozni kanal, već kao jasan ugovor između sustava: verzioniran, dokumentiran, nadziran i s jasnim odgovornostima za podatke i prava.
Ako želite naknadno uvesti REST-API za postojeći softver i pri tome od početka uskladiti arhitekturu, sigurnost i operacije, razgovarajte s nama o vašem početnom stanju i realnom planu uvođenja:
U stručnom kontekstu i autentifikacija i autorizacija igraju važnu ulogu kada je potrebno da integracije, tokovi podataka i daljnji razvoj pravilno međusobno surađuju.
Projekt ili modernizacijsko nastojanje razgovarajte s Net-Base.