Kako napraviti REST API: dizajn, sigurnost i objavljivanje
Da napravite REST API, navedite resurse kojima upravlja vaša aplikacija (korisnici, narudžbe, rezervacije), dodijelite svakom URL kao što su /orders i /orders/{id}, i koristite HTTP metode za radnje: GET za čitanje, POST za kreiranje, PATCH za izmjenu, DELETE za brisanje. Vraćajte JSON sa smislenim statusnim kodovima, validirajte svaki unos, zahtijevajte autentifikaciju i provjere 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, primjer skupa ruta, upite za AI alat za izradu aplikacija kao što je Mythex i greške koje dovode do sigurnosnih rupa. Ako su vam API-ji novi, počnite s šta je API.
Kada vam treba REST API
- Vašem web frontendu treba 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 (webhookovi)
- Posao dijelite 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 bolje rješenje.
Prvo dizajn: resursi i rute
Zapišite imenice iz vaše aplikacije i šta ljudi rade s njima. Za jednostavnu aplikaciju za rezervacije:
| Metoda | Ruta | Šta radi | Kod uspjeha |
|---|---|---|---|
GET | /api/bookings | Lista rezervacija pozivaoca (paginirano) | 200 |
POST | /api/bookings | Kreira rezervaciju | 201 |
GET | /api/bookings/{id} | Vraća jednu rezervaciju | 200 |
PATCH | /api/bookings/{id} | Mijenja neka polja | 200 |
DELETE | /api/bookings/{id} | Otkazuje rezervaciju | 204 |
GET | /api/health | Provjera ispravnosti za praćenje | 200 |
Ovo se preslikava na kreiranje, čitanje, izmjenu i brisanje; pogledajte šta je CRUD. Konvencije koje vrijedi slijediti:
- Imenice u množini, bez glagola u URL-ovima:
/bookings, a ne/getBookings. - Ugnježdavajte samo jedan nivo kada to pojašnjava vlasništvo:
/bookings/{id}/notes. - Radnje koje nisu CRUD mogu biti pod-resursi:
POST /bookings/{id}/cancelje jasnije od magične PATCH izmjene. - Dosljedna imena polja, na primjer
created_atsvuda.
Statusni kodovi i greške
Koristite standardne HTTP kodove da klijenti znaju šta se desilo bez parsiranja teksta:
| Kod | Značenje | Koristi se kada |
|---|---|---|
| 200 | OK | Uspješno čitanje ili izmjena |
| 201 | Created | POST je nešto kreirao |
| 204 | No Content | Uspjeh bez ičega 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 pravo pristupa |
| 404 | Not Found | Ne postoji, ili pozivalac ne smije znati da postoji |
| 409 | Conflict | Duplikat, ili je termin već zauzet |
| 429 | Too Many Requests | Dostignuto je ograničenje broja zahtjeva |
| 500 | Server Error | Nešto je puklo na vašoj strani |
Vraćajte greške u jednom dosljednom JSON obliku, na primjer {"error": {"code": "slot_taken", "message": "Taj termin više nije dostupan."}}, i nikada ne uključujte stack trace-ove ili greške baze u odgovorima.
Opcije i kompromisi
| Odluka | Jednostavan izbor | Alternativa |
|---|---|---|
| Gdje API živi | API rute u vašem web okviru | Poseban API servis, koristan za više klijenata ili drugi jezik |
| Autentifikacija | Session 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=...), stabilnije za velike, promjenjive liste |
| Verzionisanje | Nema dok nemate vanjske korisnike | /v1/ u putanji kada drugi zavise od njega |
| Dokumentacija | README sa listom ruta | OpenAPI specifikacija, od koje alati prave interaktivnu dokumentaciju i klijentski kod |
Korak po korak
- Navedite resurse i rute kao gore, uključujući ko smije pozvati koju.
- Modelirajte podatke u bazi sa poljima i vezama koje su vam potrebne.
- Napravite prvo rute za čitanje, pa za kreiranje, izmjenu i brisanje.
- Validirajte unos na svakom upisu pomoću biblioteke za šeme: obavezna polja, tipovi, dužine, dozvoljene vrijednosti. Odbijajte nepoznata polja.
- Dodajte autentifikaciju, pa autorizaciju za svaki zapis: učitavanje
/bookings/42mora provjeriti da rezervacija 42 pripada pozivaocu, a ne samo da je neko prijavljen. - Paginirajte svaku listu i ograničite veličinu stranice.
- Ograničite broj zahtjeva za prijavu i skupe rute. Pogledajte ograničavanje broja zahtjeva.
- Podesite CORS samo ako pregledači na drugim domenima moraju pozivati API, i eksplicitno navedite te izvore. Kako popraviti CORS greške objašnjava greške koje ćete vidjeti.
- Napišite dokumentaciju i testove za svaku rutu, uključujući slučajeve neuspjeha.
- Objavite sa tajnama u varijablama okruženja, HTTPS-om, logovima i provjerom ispravnosti.
Upiti za vaš AI alat za izradu
Skela:
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. Podatke čuvaj u našoj bazi. Validiraj tijela zahtjeva bibliotekom za šeme i odbij nepoznata polja. Greške vraćaj kao JSON {"error": {"code", "message"}} sa ispravnim statusnim kodovima (400, 401, 403, 404, 409). Tajne čuvaj u varijablama okruženja.
Sigurnost:
Zahtijevaj prijavu na svakoj ruti za rezervacije. Na svakom čitanju, izmjeni i brisanju provjeri na serveru da rezervacija pripada trenutnom korisniku; ako ne pripada, vrati 404. Nikada ne prihvataj ID-jeve korisnika ili uloge iz tijela zahtjeva. Ograniči POST /api/bookings na 20 po minuti po korisniku. Greške bilježi na serveru bez vraćanja stack trace-ova.
Dokumentacija:
Napiši OpenAPI opis ovih ruta i kratak README sa primjerima zahtjeva i odgovora za svaku.
Testiranje API-ja
Testirajte izvan frontenda, jer će to raditi napadači:
- Svaka ruta radi s ispravnim unosom i vraća dokumentovani oblik i kod
- Nedostajuća ili neispravna polja vraćaju 400 s 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; veliki
limitje ograničen - Duplikati ili sukobljena kreiranja vraćaju 409, a ne 500
- Ograničenja broja zahtjeva vraćaju 429
- Odgovori o greškama ne sadrže stack trace-ove, SQL ili tajne podatke
- CORS dozvoljava samo izvore koje namjeravate
Česte greške
- Provjera prijave bez provjere vlasništva. Najčešća rupa u API-ju: svaki prijavljeni korisnik može pročitati bilo koji zapis mijenjanjem ID-a.
- Vjerovanje klijentu. Cijene, uloge i ID-jevi korisnika iz tijela zahtjeva mogu se mijenjati.
- Vraćanje cijelih redova iz baze. Hash-evi lozinki i interna polja mogu procuriti. Birajte šta svaki odgovor sadrži.
- Neograničene liste. Jedan zahtjev za svaki zapis može usporiti cijelu aplikaciju.
200 OKsa greškom unutra. Klijenti i praćenje ne mogu znati da je nešto pošlo po zlu.- CORS postavljen da dozvoli sve na API-ju koji koristi kolačiće.
- Nema provjere ispravnosti ni logova, pa za prekide saznajete od korisnika.
Za širu provjeru prije lansiranja pogledajte sigurnosnu listu za aplikacije napravljene uz AI.
Izrada REST API-ja u Mythexu
API možete tražiti od Mythexa kao dio vaše aplikacije ili kao zaseban servis. Recept iz dokumentacije REST API backend ima početni prompt: navedite okvir i rute, tražite jasne JSON greške, čuvajte tajne u varijablama okruženja i uključite Dockerfile. Kontejnerski backendi u Node-u, Pythonu, C#-u, Javi i drugim jezicima objavljuju se preko Dockerfile-a, a Mythex vodi deploy od Publish-a (API backendi). Projekat može pokretati web stranicu i API server jedno uz drugo, a možete prebacivati između njih u pregledu. Čuvajte ključeve kao tajne vrijednosti projekta, a ako API treba bazu, zatražite je u chatu: svaki projekat može imati vlastitu Postgres bazu, uključenu na svakom planu. Agent može testirati API umjesto vas, a na Pro planu možete sami uređivati kod u uređivaču i terminalu, ili ga držati u dvosmjernoj GitHub sinhronizaciji. Za zakazani posao oko vašeg API-ja pogledajte kako pokretati pozadinske poslove.
Pitanja
Šta je REST API?
REST API je način da programi rade s podacima vaše aplikacije preko HTTP-a. Svaka vrsta podataka je resurs sa sopstvenim URL-om, na primjer /orders, a standardne metode rade s njim: GET za čitanje, POST za kreiranje, PATCH ili PUT za izmjenu i DELETE za brisanje. Podaci se obično šalju u JSON formatu.
U kojem jeziku treba praviti REST API?
Koristite ono što vi ili vaš tim možete održavati. Node.js s Expressom ili Fastifyjem, Python s FastAPI-jem, i C# ili Java okviri svi 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 web server iz Dockerfile-a, pa možete odabrati onaj koji poznajete.
Kako osigurati REST API?
Zahtijevajte autentifikaciju na svakoj ruti koja nije javna, provjerite na serveru da pozivalac smije pristupiti svakom konkretnom zapisu, validirajte sav unos, koristite HTTPS, ograničavajte broj zahtjeva i čuvajte tajne podatke u varijablama okruženja. Nikada ne vjerujte ID-jevima ili ulogama koje šalje klijent.
Treba li mi poseban backend za REST API?
Ne uvijek. Okviri poput Next.js mogu služiti API rute uz stranice. Zaseban API servis ima smisla kad više klijenata (web, mobilni, partneri) koristi API, ili kad mu treba vlastiti jezik ili skaliranje. U Mythexu web stranica i API mogu živjeti u jednom projektu i objavljivati se zajedno.