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, upite za AI alat za pravljenje aplikacija i greške koje prave 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 i GraphQL objašnjava kada jedna fleksibilna krajnja tačka za upite bolje odgovara.

Prvo dizajn: resursi i rute

Zapišite imenice iz vaše aplikacije i šta ljudi rade sa njima. Za jednostavnu aplikaciju za rezervacije:

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}/cancel je jasnije od magične PATCH izmene.
• Dosledno imenovanje polja, na primer created_at svuda.

Statusni kodovi i greške

Koristite standardne HTTP kodove da klijenti znaju šta se desilo bez čitanja teksta:

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

Korak po korak

1. Napravite listu resursa i ruta kao gore, uključujući ko sme da poziva svaku.
2. Modelirajte podatke u bazi sa poljima i vezama koje su vam potrebne.
3. Prvo napravite rute za čitanje, pa za kreiranje, izmenu i brisanje.
4. Validirajte unos na svakom upisu pomoću biblioteke za šeme: obavezna polja, tipovi, dužine, dozvoljene vrednosti. Odbacujte nepoznata polja.
5. Dodajte autentikaciju, pa autorizaciju po zapisu: učitavanje /bookings/42 mora da proveri da rezervacija 42 pripada pozivaocu, a ne samo da je neko prijavljen.
6. Paginirajte svaku listu i ograničite veličinu stranice.
7. Ograničite broj zahteva za prijavu i skupe rute. Pogledajte ograničavanje broja zahteva.
8. 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.
9. Napišite dokumentaciju i testove za svaku rutu, uključujući slučajeve neuspeha.
10. 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 limit je 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 OK sa 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

Mythex možete zamoliti za API kao deo aplikacije ili kao poseban servis. Dokumentacioni recept REST API backend ima početni upit: navedite okvir i rute, tražite jasne JSON greške, čuvajte tajne u promenljivim okruženja i uključite Dockerfile. Kontejnerski backend-i u Node, Python, C#, Java i drugim jezicima se objavljuju preko Dockerfile-a, a Mythex se brine o objavljivanju iz dela Publish (API backend-i). Projekat može da pokreće web sajt i API server jedno uz drugo, a između njih možete da prelazite u pregledu. Tajne čuvajte kao tajne projekta, a ako API treba bazu, u razgovoru to zatražite. Za poslove u pozadini oko vašeg API-ja pogledajte kako pokrenuti poslove u pozadini.

Pitanja