MODUL 1 - LEKCIJA 3

API Arhitektura: REST vs SOAP

Komunikacija između softverskih sistema: Razumijevanje API ugovora, RESTful pravila, URI dizajna, JSON-a, i bezbjednosti kroz API Gateway.

⏱️ Trajanje: ~50 min 📚 Nivo: Srednji 🎯 Koncepti: API, REST, JSON, SOAP, API Gateway

🔌 Šta je API? (Application Programming Interface)

Dok su grafički interfejsi (GUI) - poput web stranica i mobilnih aplikacija - dizajnirani da ljudi komuniciraju sa softverom, API je interfejs dizajniran da drugi softveri komuniciraju sa tim softverom.

U javnoj upravi, MUP ima svoju bazu korisnika, a Poreska Uprava ima svoju bazu poreznika. Kada referent u Poreskoj traži podatke o korisniku, Poreska baza ne smije i ne može direktno "provaliti" u MUP-ovu bazu. Umjesto toga, MUP izlaže API (Ugovor) koji kaže: "Ako mi pošaljete ovlašteni zahtjev sa JMBG-om, vratiću vam Ime i Prezime u tačno formatiranom obliku."

🌍 REST: Arhitektonski Stil modernog Weba

Zlatni standard za web API-je danas je REST (Representational State Transfer). Za razliku od nekih starijih formata, REST nije strogi kodirani protokol (nije alat), već skup pravila i dogovora kako se dizajniraju mrežne aplikacije.

6 Ključnih Ograničenja (Constraints) REST-a

  1. Client-Server Arhitektura: Vizuelni interfejs (Klijent) i čuvanje podataka (Server) moraju biti potpuno isključeni jedan iz drugog. Klijent ne zanima kako baza radi.
  2. Statelessness (Bez stanja): Najvažnije pravilo! Server ne smije pamtiti ko je korisnik između dva zahtjeva. Svaki pojedinačni HTTP zahtjev mora sadržavati sve potrebne informacije (npr. Authorization Token) da bi server shvatio ko ga zove. Ne postoji "Sesija" na serveru.
  3. Uniform Interface (Jednoobrazan Interfejs): URL adrese (URI) moraju biti predvidive, imenovane imenicama, a manipulacije se rade striktno putem HTTP Metoda (GET, POST, PUT, DELETE).
  4. Cacheability (Keširanje): Baza bi trebala reći klijentu da li podatke (npr. listu gradova) može sačuvati u RAM memoriji lokalno 30 dana, da se server ne bi gušio istim pitanjima.
  5. Layered System (Slojeviti sistem): Klijent ne zna i ne zanima ga da li komunicira direktno sa glavnim serverom baze, API Gatewayom, ili Proxy load-balancerom.
  6. Code on Demand (Opciono): Server može klijentu poslati izvršni kod (npr. JavaScript) umjesto čistih podataka.

📐 Pravilan dizajn URI-ja (Adresa) u REST-u

Jedna od najčešćih grešaka programera je korištenje "Glagola" u URL adresama. U REST-u, akcije se definišu HTTP Metodom, a URL označava samo resurs (Imenicu).

HTTP Metoda + Loš URI ❌ HTTP Metoda + Pravilan REST URI ✅ Šta to radi?
GET /dohvatiSveKorisnike GET /api/users Vraća listu (niz) svih korisnika
POST /kreirajNovogKorisnika POST /api/users Kreira novog korisnika (podaci idu u Body)
GET /dohvatiKorisnikaPola?id=14 GET /api/users/14 Vraća detalje samo o korisniku broj 14
POST /obrisiKorisnika?id=14 DELETE /api/users/14 Trajno briše korisnika iz sistema
GET /dohvatiDokumenteKorisnika?id=14 GET /api/users/14/documents Vraća sve dokumente koji pripadaju korisniku 14 (Ugniježdeni resursi)

📝 JSON (JavaScript Object Notation)

U REST komunikaciji apsolutni standard formata podataka je JSON. Razlog zašto je JSON porazio stariji XML je to što je ljudskom oku lakši za čitanje, zauzima znatno manje bajtova (nema komplikovanih zatvarajućih tagova), i JavaScript ga interpretira bez ikakve muke.

✅ Primjer JSON Payload-a (Profil Korisnika)
{
  "id": "142A9B",
  "ime": "Lejla",
  "prezime": "Spahić",
  "zaposlen": true,
  "starost": 34,
  "kontakt": {
    "email": "[email protected]",
    "telefon": "+38761234567"
  },
  "vozila": [
    "A93-M-142",
    "J12-T-900"
  ]
}

Pravila JSON-a: Ključevi (varijable) moraju biti obavijeni duplim navodnicima. Vrijednosti mogu biti stringovi (tekst), boolean (true/false), integeri (brojevi bez navodnika), liste podataka u uglastim zagradama `[]`, ili ugniježdeni objekti u vitičastim zagradama `{}`.

⚔️ SOAP vs REST u Javnom Sektoru

Pored REST-a, u sistemima javne uprave naići ćete na SOAP (Simple Object Access Protocol) servise. Dok je REST arhitektonski stil, SOAP je strogi protokol koji se oslanja isključivo na XML.

Zašto institucije vole SOAP?

Mnogi centralni registri u upravi (nastali oko 2010. godine) koriste SOAP zbog njegovih sigurnosnih ugovora (WS-Security), kao i sistema automatskog generisanja klijentskog koda baziranog na WSDL (Web Services Description Language) dokumentu. U SOAP-u se tačno zna koliko je poruka stotinki dugačka, i ako ispadne jedno XML slovo, server kategorički odbija zahtjev.

SOAP (Stari Centralni Registar)

Glomazan i težak (XML Envelopes). Sve ide preko HTTP POST-a, čak i obično čitanje podataka.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <sec:Security><sec:Token>123</sec:Token></sec:Security>
  </soapenv:Header>
  <soapenv:Body>
    <gov:GetStatusPredmeta>
      <gov:Broj>101</gov:Broj>
    </gov:GetStatusPredmeta>
  </soapenv:Body>
</soapenv:Envelope>

REST (Moderna e-Uprava API)

Munjevito brz, elegantan JSON, koristi HTTP metode ispravno (GET u ovom slučaju).

GET /api/predmeti/101/status HTTP/1.1
Authorization: Bearer my_jwt_token_123
Accept: application/json

🛡️ API Gateway (Zaštitni Zid Mikrousluga)

Moderni sistemi institucija su izgrađeni uz pomoć destina različitih Servera. Da bi korisnici i druge Agencije sigurno pristupale tim servisima, izbjegava se javno izlaganje baze, te se postavlja API Gateway.

Korisnik
(Web Portal)
➔
API Gateway
(Rate Limiting, Auth)
➔
Poreski Servis
MUP Servis
Zemljišni Servis

Svi dolazni zahtjevi prolaze apsolutnu sigurnosnu kontrolu prije usmjeravanja ka zatvorenim mikroservisima.

API Gateway poput Kong, Ocelot (C#), ili Azure API Management vrši ulogu vratara. Njegovi glavni zadaci su: