Kako napraviti REST API: dizajn, bezbednost i objavljivanje
Da biste napravili REST API, napravite spisak resursa kojima vaša aplikacija upravlja (korisnici, porudžbine, rezervacije), dodelite svakom URL adresu, poput /orders i /orders/{id}, i koristite HTTP metode za radnje: GET za čitanje, POST za kreiranje, PATCH za izmenu i DELETE za brisanje. Vraćajte JSON sa smislenim statusnim kodovima, validirajte svaki unos, zahtevajte autentikaciju i provere dozvola za svaki zapis na serveru i paginirajte liste. Zatim dokumentujte krajnje tačke i objavite API iza HTTPS-a.
Ovaj vodič pokriva odluke o dizajnu, primer skupa ruta, promptove za AI alat za izradu aplikacija kao što je Mythex i greške koje otvaraju bezbednosne rupe. Ako su vam API-ji novi, počnite sa šta je API.
Kada vam treba REST API
- Vaš web frontend mora da čuva i učitava podatke sa servera
- Mobilnoj aplikaciji, partneru ili alatu za automatizaciju treba pristup vašim podacima
- Drugi servisi vam šalju događaje (webhook-ovi)
- Posao delite između frontend i backend tima
REST je najčešći stil, ali nije jedini. REST vs GraphQL objašnjava kada je jedan fleksibilan endpoint za upite bolji izbor.
Prvo dizajn: resursi i rute
Zapišite imenice iz vaše aplikacije i šta ljudi rade sa njima. Za jednostavnu aplikaciju za rezervacije:
| Metoda | Ruta | Šta radi | Kod uspeha |
|---|---|---|---|
GET | /api/bookings | Prikazuje rezervacije pozivaoca (paginirano) | 200 |
POST | /api/bookings | Kreira rezervaciju | 201 |
GET | /api/bookings/{id} | Prikazuje jednu rezervaciju | 200 |
PATCH | /api/bookings/{id} | Menja neka polja | 200 |
DELETE | /api/bookings/{id} | Otkazuje rezervaciju | 204 |
GET | /api/health | Provera zdravlja za praćenje | 200 |
Ove rute odgovaraju kreiranju, čitanju, izmeni i brisanju; pogledajte šta je CRUD. Konvencije koje vredi pratiti:
- Množina i imenice, bez glagola u URL-ovima:
/bookings, a ne/getBookings. - Ugnježdavajte samo jedan nivo kada to jasno pokazuje vlasništvo:
/bookings/{id}/notes. - Radnje koje nisu CRUD mogu biti pod-resursi:
POST /bookings/{id}/cancelje jasnije od magične PATCH izmene. - Dosledno imenovanje polja, na primer
created_atsvuda.
Statusni kodovi i greške
Koristite standardne HTTP kodove da klijenti znaju šta se desilo bez čitanja teksta:
| Kod | Značenje | Kada se koristi |
|---|---|---|
| 200 | OK | Uspešno čitanje ili izmena |
| 201 | Created | POST je kreirao nešto |
| 204 | No Content | Uspeh bez podataka za vraćanje |
| 400 | Bad Request | Unos nije prošao validaciju |
| 401 | Unauthorized | Niste prijavljeni ili je token neispravan |
| 403 | Forbidden | Prijavljeni ste, ali nemate dozvolu |
| 404 | Not Found | Ne postoji, ili pozivalac ne sme da zna da postoji |
| 409 | Conflict | Duplikat, ili je termin već zauzet |
| 429 | Too Many Requests | Dostignut je limit zahteva |
| 500 | Server Error | Nešto je puklo na vašoj strani |
Vraćajte greške u jednom dosledno oblikovanom JSON-u, na primer {"error": {"code": "slot_taken", "message": "Taj termin više nije dostupan."}}, i nikada ne uključujte stek-tragove ni greške baze u odgovorima.
Opcije i kompromisi
| Odluka | Jednostavan izbor | Alternativa |
|---|---|---|
| Gde API živi | API rute u vašem web okviru | Poseban API servis, koristan za više klijenata ili drugi jezik |
| Autentikacija | Sesijski kolačići za vašu web aplikaciju | Tokeni (bearer tokeni ili API ključevi) za mobilne aplikacije i treće strane |
| Paginacija | ?page=2&limit=20 | Kursor (?after=...), stabilnija za velike liste koje se menjaju |
| Verzionisanje | Nema, dok nemate spoljne korisnike | /v1/ u putanji kada drugi zavise od njega |
| Dokumentacija | README sa listom ruta | OpenAPI specifikacija, iz koje alati prave interaktivnu dokumentaciju i klijentski kod |
Korak po korak
- Napravite listu resursa i ruta kao gore, uključujući ko sme da poziva svaku.
- Modelirajte podatke u bazi sa poljima i vezama koje su vam potrebne.
- Prvo napravite rute za čitanje, pa za kreiranje, izmenu i brisanje.
- Validirajte unos na svakom upisu pomoću biblioteke za šeme: obavezna polja, tipovi, dužine, dozvoljene vrednosti. Odbacujte nepoznata polja.
- Dodajte autentikaciju, pa autorizaciju po zapisu: učitavanje
/bookings/42mora da proveri da rezervacija 42 pripada pozivaocu, a ne samo da je neko prijavljen. - Paginirajte svaku listu i ograničite veličinu stranice.
- Ograničite broj zahteva za prijavu i skupe rute. Pogledajte ograničavanje broja zahteva.
- Podesite CORS samo ako browser-i sa drugih domena moraju da zovu API, i eksplicitno navedite te izvore. Kako rešiti CORS greške objašnjava greške koje ćete videti.
- Napišite dokumentaciju i testove za svaku rutu, uključujući slučajeve neuspeha.
- Objavite sa tajnama u promenljivim okruženja, HTTPS-om, logovima i proverom zdravlja.
Upiti za vaš AI alat
Kostur:
Napravi REST API za rezervacije sa ovim rutama: GET /api/health, GET /api/bookings (paginirano, najviše 50 po stranici), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Čuvaj podatke u našoj bazi. Validiraj telo zahteva pomoću biblioteke za šeme i odbij nepoznata polja. Vraćaj greške u JSON-u kao {"error": {"code", "message"}} sa ispravnim statusnim kodovima (400, 401, 403, 404, 409). Čuvaj tajne u promenljivim okruženja.
Bezbednost:
Zahtevaj prijavu na svakoj ruti za rezervacije. Na svakom čitanju, izmeni i brisanju proveri na serveru da rezervacija pripada trenutnom korisniku; ako ne pripada, vrati 404. Nikada ne prihvataj ID korisnika ili uloge iz tela zahteva. Ograniči POST /api/bookings na 20 zahteva u minuti po korisniku. Beleži greške na serveru bez vraćanja stek-tragova.
Dokumentacija:
Napiši OpenAPI opis ovih ruta i kratak README sa primerima zahteva i odgovora za svaku rutu.
Testiranje API-ja
Testirajte spolja, izvan frontenda, jer će to raditi i napadači:
- Svaka ruta radi sa ispravnim unosom i vraća dokumentovani oblik i kod
- Nedostajuća ili neispravna polja vraćaju 400 sa jasnom porukom
- Bez tokena svaka zaštićena ruta vraća 401
- Korisnik A koji traži zapis korisnika B po ID-u dobija 404 ili 403
- Liste su paginirane, a ogromna vrednost
limitje ograničena - Duplikati ili sukobi pri kreiranju vraćaju 409, a ne 500
- Limiti zahteva vraćaju 429
- Odgovori o greškama ne sadrže stek-tragove, SQL ili tajne
- CORS dozvoljava samo izvore koje ste nameravali
Česte greške
- Provera prijave, ali ne i vlasništva. Najčešća rupa u API-ju: bilo koji prijavljeni korisnik može da čita bilo koji zapis promenom ID-ja.
- Verovanje klijentu. Cene, uloge i ID-jevi korisnika iz tela zahteva mogu da se izmene.
- Vraćanje celih redova iz baze. Heševi lozinki i interna polja cure. Birajte šta svaki odgovor sadrži.
- Liste bez ograničenja. Jedan zahtev za svaki zapis može da uspori celu aplikaciju.
200 OKsa porukom o grešci unutra. Klijenti i praćenje ne mogu da vide da je zahtev pao.- CORS podešen da dozvoljava sve na API-ju koji koristi kolačiće.
- Nema provere zdravlja ni logova, pa za prekide saznajete od korisnika.
Za širu proveru pre lansiranja pogledajte bezbednosnu listu za aplikacije napravljene uz AI.
Pravljenje REST API-ja u Mythex-u
API možete da zatražite od Mythex-a kao deo aplikacije ili kao zaseban servis. Recept iz dokumentacije REST API backend ima početni prompt: navedite okvir i rute, zatražite jasne JSON greške, čuvajte tajne u promenljivim okruženja i uključite Dockerfile. Kontejnerski backendi u Node-u, Pythonu, C#-u, Javi i drugima objavljuju se preko Dockerfile-a, a Mythex se brine o deploy-u iz Publish-a (API backendi). Projekat može da pokreće sajt i API server jedan pored drugog, a između njih možete da prelazite u pregledu. Čuvajte ključeve kao tajne projekta, a ako API treba bazu podataka, zatražite je u chatu: svaki projekat može imati sopstvenu Postgres bazu podataka, uključenu u svaki plan. Agent može da testira API umesto vas, a na Pro planu možete sami da menjate kod u editoru i terminalu ili da ga držite u dvosmernoj sinhronizaciji sa GitHub-om. Za zakazan posao oko vašeg API-ja pogledajte kako pokrenuti pozadinske poslove.
Pitanja
Šta je REST API?
REST API je način da programi rade sa podacima vaše aplikacije preko HTTP-a. Svaka vrsta podataka je resurs sa sopstvenom URL adresom, na primer /orders, a standardne metode rade sa njim: GET za čitanje, POST za kreiranje, PATCH ili PUT za izmenu i DELETE za brisanje. Podaci se obično šalju u JSON formatu.
U kom jeziku da pravim REST API?
Koristite ono što vi ili vaš tim možete da održavate. Node.js sa Express ili Fastify, Python sa FastAPI i C# ili Java okviri dobro funkcionišu. Pravila dizajna za rute, statusne kodove, validaciju i autentifikaciju važnija su od jezika. Mythex pokreće API-je u Node-u, Pythonu, Javi, C#-u ili bilo čemu što radi kao veb server iz Dockerfile-a, pa možete odabrati onaj koji znate.
Kako da obezbedim REST API?
Zahtevajte autentikaciju na svakoj ruti koja nije javna, na serveru proverite da li pozivalac sme da pristupi svakom konkretnom zapisu, validirajte sav unos, koristite HTTPS, ograničite broj zahteva i čuvajte tajne u promenljivim okruženja. Nikada ne verujte ID-jevima ili ulogama koje šalje klijent.
Da li mi je potreban poseban backend za REST API?
Nije uvek. Okviri poput Next.js mogu da služe API rute uz stranice. Zaseban API servis ima smisla kad više klijenata (veb, mobilni, partneri) koristi isti API ili kad mu treba sopstveni jezik ili skaliranje. U Mythex-u sajt i API mogu da žive u jednom projektu i da se objave zajedno.