Kako prototipirati API prije nego backend postoji

Mnogi API projekti krenu po zlu jer prvi shared artifact nije contract. To je controller, database table ili napola dovršeno okruženje koje može pokrenuti samo jedan developer.

To je obično skup način da naučite što je API trebao biti.

Ako frontend, partner ili interni consumer već zna koje podatke treba, bolji je potez prototipirati API prije nego backend postoji. To znači najprije definirati contract, mockati ga, testirati happy path i očite failure slučajeve, a tek onda zaključati implementaciju oko njega.

Zašto je to danas važnije

Trenutne Postman API design smjernice i dalje guraju istu prakticnu ideju: radite outside-in, a ne inside-out. Krenite od onoga što consumerima treba da API napravi, a ne od toga kako vam tablice danas izgledaju.

To se dobro uklapa s OpenAPI-jem. Formalna specifikacija olakšava review endpointa, validaciju request i response oblika, dokumentiranje autha i generiranje collectiona, testova i client koda prije nego su production logic dijelovi dovršeni. Umjesto da prerano raspravljate o implementacijskim detaljima, tim može raspravljati o interfaceu dok je cijena promjene još uvijek niska.

Bolji redoslijed rada

Koristite ovaj slijed kada će API koristiti više ekrana, timova ili sustava:

1. Napisite OpenAPI contract za prvi stvarni use case.
2. Definirajte request bodyje, response oblike, auth zahtjeve i error stanja.
3. učitajte contract u Postman i kreirajte example pozive i mock responses.
4. Pustite frontend ili integration consumera da testira protiv mocka prije nego backend bude gotov.
5. Pretvorite najvažnije primjere u contract testove kako implementacija ne bi driftala.

Taj redoslijed otkriva greške u dizajnu rano. Pronalazite probleme s imenovanjem, nedostajuće fieldove, slabu obradu grešaka i neugodan auth flow dok je sustav još jeftin za promjenu.

Što prvo prototipirati

Nemojte pokušati opisati cijelu platformu u jednom prolazu.

Krenite s jednom uskom putanjom koja je važna, poput stvaranja ordera, dohvaćanja customer zapisa ili sinkronizacije leada u CRM. Ako je taj put jasan, ostatak API-ja obično postaje lakši za oblikovati.

Poanta nije stvoriti lijepu dokumentaciju radi dokumentacije. Poanta je učiniti contract dovoljno konkretnim da ga druga osoba može koristiti bez pogađanja što je backend developer mislio.

Kada ovaj pristup najviše pomaže

API-first prototipiranje je posebno korisno kada:

1. Frontend i backend rade paralelno.
2. Treba postojati third-party integracija koja ovisi o contractu.
3. API bi kasnije mogao trebati SDK-ove, dokumentaciju ili javnu izlozenost.
4. Tim je već stradao zbog implementation drift-a.

Manje je važno za sitan interni endpoint koji će samo jedan servis pozvati jednom. Ali čim interface postane shared infrastructure, contract-first workflow obično vraća ulozeno.

Praktično pravilo

Ako će dvije osobe morati računati na API, tretirajte contract kao proizvod prije nego što backend bude proizvod. Prototipirajte interface, mockajte ga, reviewajte i testirajte dok je promjena još uvijek jeftina.

Official resources: Postman API Design i OpenAPI Initiative.