Razvoj REST API-ja i integracija servisa

Razvoj REST API-ja određuje kako vaš softver komunicira sa svim ostalim sistemima: mobilnom aplikacijom, web shopom, partnerima, knjigovodstvenim programom i desetinama SaaS alata koje vaša firma već plaća. Dobro osmišljen API pretvara te sisteme u jedan tok rada – narudžbe stižu u ERP, plaćanja ažuriraju fakture, stanje zaliha se vidi na svim prodajnim kanalima. Loše osmišljen API postaje mjesto na kojem se podaci tiho gube, a svaka nova funkcionalnost traje duplo duže nego što bi trebalo.

Sadržaj

U CodeWizu dizajniramo, razvijamo i dokumentujemo REST API-je po mjeri i povezujemo postojeće aplikacije sa servisima trećih strana: payment providerima, CRM sistemima, kurirskim službama, marketplace platformama i AI servisima. Posebnu pažnju posvećujemo onome što odlučuje da li će API preživjeti stvarni saobraćaj: dosljednom dizajnu resursa, jasnom rukovanju greškama, idempotentnim upisima, ponovnim pokušajima (retry), verzionisanju, dokumentaciji i razumnim ograničenjima.

Usluga je namijenjena firmama koje prave mobilnu ili single-page aplikaciju i trebaju backend, kompanijama koje žele prestati ručno prepisivati podatke iz jednog alata u drugi, SaaS proizvodima koji otvaraju javni ili partnerski API, te timovima čije se postojeće integracije kvare svaki put kada dobavljač nešto promijeni. Bilo da vam treba jedna integracija ili kompletna API platforma, cilj je isti: pouzdana razmjena podataka koju vaš tim razumije i može dalje razvijati.

Kod teme integracije alati otvorenog koda su prvi izbor kada odgovaraju poslu.

Razvoj REST API-ja po mjeri vašeg poslovanja

API po mjeri počinje od vašeg domena, a ne od frameworka. Prije pisanja koda mapiramo resurse (kupce, narudžbe, rezervacije, dokumente), ko ih smije čitati ili mijenjati i koje operacije moraju biti brze, atomske ili asinhrone. Taj model postaje ugovor (contract) na koji se frontend, mobilni i partnerski programeri mogu oslanjati godinama.

Integracije kreće od sistema koji već radi, a ne od praznog šablona.

Principi dizajna koje primjenjujemo na svaki API

Predvidljivi resursi i metode: imenice u množini (/orders, /orders/{id}/items), ispravne HTTP metode i statusni kodovi – 201 sa Location headerom pri kreiranju, svjesno razlikovanje 404 i 403, 409 za konflikte i 422 za greške validacije.
Jedan format grešaka svuda: koristimo standard Problem Details (RFC 9457), pa svaki klijent obrađuje greške na isti način umjesto da parsira improvizovane poruke.
Paginacija zasnovana na kursoru za velike kolekcije ili one koje se često mijenjaju, uz filtriranje, sortiranje i biranje polja, tako da mobilni klijenti ne preuzimaju podatke koje nikada ne prikazuju.
Idempotency ključevi za upise: klijent koji ponovi POST /payments nakon timeouta ne smije dva puta naplatiti kupca.
Verzionisanje od prvog dana: prefiks /v1 ili header sa verzijom, promjene koje samo dodaju stvari kao pravilo i objavljena politika gašenja (deprecation) za one koje nešto lome.
Keširanje i kontrola istovremenih izmjena: ETag i If-None-Match za jeftino ponovno čitanje, If-Match da dva korisnika ne bi prepisala tuđe izmjene.

Ovako klijent vidi dosljednu grešku validacije:

Rad na temi integracije ostaje u vašem repozitoriju i na vašoj infrastrukturi.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "message": "Must be a valid email address" },
    { "field": "quantity", "message": "Must be at least 1" }
  ]
}

Izbor tehnologije

API razvijamo u jeziku koji odgovara vašem timu i postojećim sistemima, umjesto da jednu tehnologiju guramo u svaki projekat:

Tehnologija	Prednosti	Tipična upotreba	Kompromisi
Laravel (PHP)	Brza isporuka, Eloquent ORM, ugrađeni queue sistem, Sanctum i Passport	Poslovni backend, e-commerce, proizvodi sa mnogo administracije	Za vrlo velik broj zahtjeva treba Octane ili pažljivo podešavanje
Node.js (Fastify, NestJS, Express)	Neblokirajući I/O, zajednički TypeScript tipovi sa frontendom	Integracioni hubovi, funkcije u realnom vremenu, BFF slojevi	Posao koji opterećuje CPU mora ići u workere
Python (FastAPI)	Automatska OpenAPI dokumentacija, Pydantic validacija, AI i data biblioteke	AI/ML servisi, obrada podataka, backend za scraping	Async ekosistem je manje ujednačen nego kod Node.js-a
Go	Vrlo niska latencija i potrošnja memorije, jedan statički binarni fajl	Servisi sa velikim protokom, proxy servisi, interni alati	Više koda za stvari koje frameworci daju besplatno

Tipično isporučujemo sam API sa automatskim testovima, OpenAPI specifikaciju, migracije baze podataka, Docker okruženje, CI pipeline i kratko uputstvo za održavanje.

Integracije: Gomila šarenih dijelova slagalice koji čekaju da budu povezani

Integracije sa servisima trećih strana koje ne pucaju

Većini firmi ne treba još softvera, nego da softver koji već imaju međusobno dijeli podatke. Integrišemo payment providere (Stripe, PayPal, regionalne procesore kartica), CRM sisteme (HubSpot, Pipedrive, Salesforce), knjigovodstvene i ERP sisteme, kurirske službe, marketplace platforme, email i SMS servise, Google i Meta API-je, kao i AI servise poput OpenAI-ja ili modela koje hostujete sami. Plaćanja zahtijevaju posebnu pažnju, o čemu pišemo u članku o sigurnoj integraciji payment gatewaya.

Šta integraciju čini pouzdanom

Redovi (queues) umjesto direktnih poziva: spor CRM nikada ne smije usporiti checkout. Odlazne pozive šaljemo u Laravel queue, BullMQ ili message broker i obrađujemo ih u workerima.
Ponovni pokušaji sa eksponencijalnim čekanjem i jitterom za timeoute i 5xx odgovore, bez ponavljanja kod trajnih 4xx grešaka.
Circuit breaker i timeout na svakom odlaznom zahtjevu, tako da jedan dobavljač u kvaru ne može iscrpiti sve konekcije.
Provjereni webhookovi bez duplikata: provjeravamo potpise, čuvamo ID događaja i svaki događaj obrađujemo tačno jednom, čak i kada ga dobavljač pošalje tri puta.
Poslovi usklađivanja (reconciliation) koji povremeno porede oba sistema i ispravljaju razlike nastale zbog propuštenih webhookova.
Higijena pristupnih podataka: API ključevi u sigurnom skladištu tajni, sa minimalnim ovlaštenjima i rotacijom bez izmjene koda.

Provjera webhooka je kratka, ali se često preskače. Minimalna HMAC provjera u Node.js-u izgleda ovako:

import crypto from "node:crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Poređenje se izvršava u konstantnom vremenu, a potpis se računa nad sirovim tijelom zahtjeva, ne nad parsiranim JSON-om – detalj zbog kojeg mnoge integracije prestanu raditi nakon nadogradnje frameworka.

Otvorena knjiga sa trakom za označavanje na svijetlom stolu

API dokumentacija koju programeri zaista koriste

API dokumentacija je dio proizvoda. Bez nje svaka integracija počinje pozivom vašim programerima, a sa njom partneri i vaš frontend tim mogu raditi samostalno. Svaki API koji napravimo dokumentujemo OpenAPI 3.1 specifikacijom i pretvaramo je u pregledne referentne stranice.

Design-first ili code-first

Za javne i partnerske API-je preferiramo design-first pristup: OpenAPI ugovor se piše i pregleda prije implementacije, pa frontend programeri mogu raditi nad mock serverom (Prism) dok je backend još u izradi. Za interne API-je, code-first generisanje iz anotacija ili tipova (FastAPI, NestJS Swagger, Scramble za Laravel) uz minimalan trud drži dokumentaciju usklađenom sa kodom. U oba slučaja specifikacija živi u Gitu, a izmjene prolaze code review.

paths:
  /v1/orders/{id}:
    get:
      summary: Get a single order
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
        "404":
          $ref: "#/components/responses/NotFound"

Šta sadrži dobra dokumentacija

Interaktivne referentne stranice generisane alatima Redoc, Scalar ili Swagger UI.
Vodič za početak: autentifikacija, prvi zahtjev i najčešći tokovi od početka do kraja.
Stvarne primjere zahtjeva i odgovora za svaki endpoint, uključujući greške.
Postman ili Bruno kolekcije i, gdje ima smisla, generisane klijentske SDK biblioteke.
Changelog i raspored gašenja starih verzija, da korisnici API-ja znaju šta se mijenja i kada.
Contract testove (Schemathesis ili Dredd) u CI-ju koji padaju čim implementacija odstupi od specifikacije.

Svjetlosni tragovi saobraćaja na autoputu noću, duga ekspozicija

Rate limiting i kvote korištenja vašeg API-ja

Svakom API-ju trebaju ograničenja. Rate limiting štiti servere od naglih skokova saobraćaja, klijenata sa greškom koji se vrte u petlji, credential stuffing napada i scrapera, a sprečava i da jedan zahtjevan klijent uspori servis svima ostalima. Kod SaaS proizvoda kvote su često i dio cjenovnog modela.

Algoritam	Kako radi	Dobar za	Slabost
Fixed window	Broji zahtjeve po minuti ili satu	Jednostavne kvote, dnevna ograničenja	Navale na granici prozora mogu udvostručiti dozvoljeni broj zahtjeva
Sliding window	Ponderisan broj zahtjeva u kliznom periodu	Pravedna ograničenja po korisniku na javnim API-jima	Nešto više memorije i računanja
Token bucket	Tokeni se dopunjuju ravnomjerno, svaki zahtjev troši jedan	Dozvoljavanje kratkih navala uz stabilan prosjek	Klijentima je teže predvidjeti ponašanje

Kako ga implementiramo

Ograničenja po API ključu ili korisniku, a ne samo po IP adresi, uz posebne nivoe za anonimne, prijavljene i premium klijente.
Stroža ograničenja za skupe ili osjetljive endpointe: prijavu, pretragu, izvoz podataka, AI pozive.
Zajednički brojači u Redisu, tako da ograničenja važe i kada aplikacija radi na više servera.
Jasni odgovori: 429 Too Many Requests sa Retry-After i rate limit headerima, da dobro napisani klijenti uspore umjesto da zasipaju API zahtjevima.
Zaštita na edge nivou kroz Cloudflare ili gateway protiv masovnih napada, a ograničenja u aplikaciji za poslovna pravila.

O ovoj temi objavili smo dva detaljna vodiča: kompletan vodič za API rate limiting i praktičan prikaz rate limitinga u Node.js-u i Expressu.

REST, GraphQL, gRPC ili webhookovi: koji stil API-ja izabrati

REST je pravi izbor za većinu poslovnih API-ja, ali nije jedina opcija. Stil preporučujemo prema tome ko koristi API i na koji način:

Stil	Najbolji kada	Izbjegavati kada
REST	Javni ili partnerski API-ji, domeni sa mnogo CRUD operacija, važno je HTTP keširanje	Klijentima trebaju vrlo različiti oblici istih podataka
GraphQL	Više frontenda sa različitim potrebama, duboko povezani podaci	Jednostavan CRUD, veliko oslanjanje na CDN keširanje
gRPC	Interna komunikacija između servisa, niska latencija, streaming	Browser klijenti bez proxyja, eksterni korisnici
Webhookovi	Obavještavanje drugih sistema kada se nešto desi	Primalac ne može izložiti javni endpoint

Mnogi sistemi ih kombinuju: REST API za partnere, webhookove za događaje i gRPC između internih servisa.

Osnove sigurnosti API-ja

API direktno izlaže vaše podatke, pa se sigurnost ugrađuje od početka, a ne dodaje naknadno. OWASP API Security Top 10 je naša kontrolna lista, a najčešći problem u praksi je i dalje neispravna autorizacija na nivou objekta: endpoint koji vraća /orders/1043 svakom prijavljenom korisniku, a ne samo vlasniku narudžbe.

Provjera autorizacije za svaki objekat, centralizovana u policy klasama umjesto razbacana po kontrolerima.
Stroga validacija ulaza i eksplicitna serijalizacija izlaza, da interna polja nikada ne procure.
Autentifikacija tokenima (OAuth 2.0, JWT ili Laravel Sanctum) sa kratkotrajnim tokenima i API ključevima ograničenih ovlaštenja.
TLS svuda, CORS ograničen na poznate domene i sigurnosni headeri u svakom odgovoru.
Audit logovi za osjetljive operacije i upozorenja na neuobičajene obrasce pristupa.

Testiranje, verzionisanje i nadzor API-ja u produkciji

API je dobar onoliko koliko se dobro ponaša u lošem danu. Za svaki endpoint pišemo feature testove (Pest ili PHPUnit, Jest ili Vitest, pytest), contract testove prema OpenAPI specifikaciji i load testove alatom k6 za kritične tokove. U produkciji pratimo percentile latencije, stopu grešaka po endpointu i po klijentu, kao i spore upite prema bazi, uz strukturirane logove i request ID koji prati poziv kroz sve servise. Provjere dostupnosti otkrivaju ispade prije kupaca – osnovne potrebe pokriva već i self-hosted monitor dostupnosti.

Najčešće greške u REST API-jima koje ispravljamo

Vraćanje 200 OK sa porukom o grešci u tijelu odgovora, pa klijenti ne mogu pouzdano prepoznati neuspjeh.
Izlaganje tabela iz baze jedan-na-jedan kao endpointa, čime je svaki klijent vezan za vašu šemu.
N+1 upiti skriveni iza endpointa za liste, koji postaju sve sporiji kako podaci rastu.
Nedostatak paginacije, pa zahtjev za „sve narudžbe” s vremenom završi timeoutom ili potroši svu memoriju.
Izmjene koje lome kompatibilnost objavljene bez nove verzije, a partneri ih otkriju u produkciji.
Sinhroni pozivi servisima trećih strana unutar korisničkog zahtjeva, i to bez timeouta.

Kako radimo

Analiza: mapiramo sisteme koji učestvuju, podatke koji moraju teći između njih, korisnike API-ja i nefunkcionalne zahtjeve poput obima, latencije i usklađenosti sa propisima.
Ugovor: resurse, endpointe, greške i autentifikaciju dizajniramo u OpenAPI specifikaciji i pregledamo je sa vama i vašim frontend ili partnerskim timovima.
Razvoj: implementiramo API i integracije sa redovima, ponovnim pokušajima, logovanjem i automatskim testovima, isporučujući u malim koracima koje možete isprobati na stagingu.
Testiranje: pokrećemo contract, integracione i load testove, simuliramo kvarove poput ispada dobavljača i provjeravamo sigurnost prema OWASP API Top 10.
Puštanje u rad: objavljujemo API sa uključenim nadzorom i upozorenjima i objavljujemo dokumentaciju za korisnike.
Podrška: održavamo integracije kada dobavljači promijene svoje API-je, dodajemo endpointe i vodimo prelaske na nove verzije.

Zašto CodeWiz

Full-stack perspektiva: sami pravimo frontende, mobilne backende i infrastrukturu koja koristi API-je, pa dizajniramo API-je koje je prijatno koristiti, a ne samo ispravne.
Široko iskustvo sa integracijama: plaćanja, e-commerce platforme, pretraga, scraping, AI i automatizacija dio su našeg svakodnevnog rada.
Otvoreni standardi, bez zaključavanja: OpenAPI, open-source frameworci i dokumentacija sa kojom svaki stručan tim može preuzeti projekat.
Rješenja po mjeri: jedna integracija ili cijela API platforma – obim prilagođavamo onome što vašem poslovanju zaista treba.
Fer cijene: vrhunski razvoj bez vrhunskih cijena, iz Banje Luke, uz rad na daljinu sa klijentima iz regiona i inostranstva. Saznajte više o CodeWizu.

Često postavljana pitanja

Koliko košta razvoj REST API-ja po mjeri?

Cijena zavisi od broja resursa i endpointa, složenosti poslovnih pravila, broja uključenih sistema trećih strana i zahtjeva za dokumentacijom i sigurnošću. Jedna integracija između dva sistema je mali projekat, a javna API platforma sa SDK bibliotekama i paketima korištenja veliki. Nakon analize dobijate jasno definisan obim i procjenu.

Koliko traje izrada API-ja ili integracije?

Fokusirana integracija, recimo sinhronizacija narudžbi iz web shopa u knjigovodstveni program, obično traje od nekoliko dana do dvije sedmice, uključujući testiranje. Kompletan backend API za novi proizvod najčešće traje nekoliko sedmica i isporučuje se u fazama, tako da vaš frontend tim može početi rano.

Možete li integrisati sistem koji ima lošu dokumentaciju ili je nema uopšte?

Često možemo. Analiziramo postojeći saobraćaj, SDK biblioteke dobavljača i ponašanje sandbox okruženja, a krhke sisteme zatvaramo iza čistog internog API-ja kako bi ostatak vašeg sistema bio zaštićen od njihovih neobičnosti. Tamo gdje API uopšte ne postoji, opcija može biti pažljivo preuzimanje podataka.

Da li moj API treba biti REST ili GraphQL?

Za većinu poslovnih i partnerskih API-ja REST je jednostavniji za keširanje, zaštitu i dokumentovanje. GraphQL se isplati kada više frontenda treba vrlo različite poglede na bogato povezane podatke. Preporučićemo opciju koja odgovara korisnicima vašeg API-ja, a oba pristupa mogu postojati paralelno.

Da li održavate integracije nakon puštanja u rad?

Da. Dobavljači redovno gase endpointe i mijenjaju formate podataka. Možemo nadzirati integracije, ažurirati ih kada se provajderi promijene i proširivati API kako vaše poslovanje raste.

Treba vam pouzdan API ili integracija?

Recite nam koji sistemi treba da komuniciraju i gdje danas zapinju podaci, a mi ćemo predložiti dizajn API-ja i plan integracije koji odgovara vašem budžetu. Kontaktirajte nas da razgovaramo o projektu ili pogledajte naše usluge razvoja REST API-ja i integracija.

Razvoj REST API-ja i integracija servisa