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 i greške koje dovode do sigurnosnih propusta. Ako su API-ji novi za vas, 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 najrašireniji stil, ali nije jedini. REST vs 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 s njima. Za jednostavnu aplikaciju za rezervacije:

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}/cancel je jasnije od magične PATCH izmjene.
• Dosljedna imena polja, na primjer created_at svuda.

Statusni kodovi i greške

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

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

Korak po korak

1. Navedite resurse i rute kao gore, uključujući ko smije pozvati koju.
2. Modelirajte podatke u bazi sa poljima i vezama koje su vam potrebne.
3. Napravite prvo rute za čitanje, pa za kreiranje, izmjenu i brisanje.
4. Validirajte unos na svakom upisu pomoću biblioteke za šeme: obavezna polja, tipovi, dužine, dozvoljene vrijednosti. Odbijajte nepoznata polja.
5. Dodajte autentifikaciju, pa autorizaciju za svaki zapis: učitavanje /bookings/42 mora provjeriti 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 zahtjeva za prijavu i skupe rute. Pogledajte ograničavanje broja zahtjeva.
8. 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.
9. Napišite dokumentaciju i testove za svaku rutu, uključujući slučajeve neuspjeha.
10. 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 limit je 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 OK sa 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

U Mythexu možete zatražiti API kao dio aplikacije ili kao zaseban servis. Recept u dokumentaciji REST API backend ima početni upit: navedite okvir i rute, tražite jasne JSON greške, čuvajte tajne u varijablama okruženja i uključite Dockerfile. Kontejnerski backendi u Node, Python, C#, Java i drugim jezicima objavljuju se preko Dockerfile-a, a Mythex vodi objavu iz Publish-a (API backendi). Projekat može istovremeno pokretati web stranicu i API server, a između njih možete prebacivati u pregledu. Tajne čuvajte kao tajne projekta, a ako API treba bazu, zatražite je u chatu. Za zakazane poslove oko vašeg API-ja pogledajte kako pokrenuti pozadinske poslove.

Pitanja