Kako zgraditi REST API: zasnova, varnost in objava

Za gradnjo REST API-ja najprej popišite vire, ki jih vaša aplikacija upravlja (uporabniki, naročila, rezervacije), vsakemu dodelite URL, na primer /orders in /orders/{id}, za dejanja pa uporabite metode HTTP: GET za branje, POST za ustvarjanje, PATCH za posodobitev in DELETE za brisanje. Vračajte JSON z ustreznimi statusnimi kodami, validirajte vsak vnos, na strežniku zahtevajte avtentikacijo in preverjanje pravic za vsak zapis ter rezultate delite na strani. Nato dokumentirajte končne točke in API objavite za HTTPS.

Ta vodnik pokriva zasnovne odločitve, primer nekaterih poti, pozive za AI graditelja aplikacij in napake, ki povzročajo varnostne luknje. Če so API-ji za vas nova stvar, najprej preberite kaj je API.

Kdaj potrebujete REST API

• Vaš spletni frontend mora na strežnik shranjevati in iz njega nalagati podatke
• Mobilna aplikacija, partner ali orodje za avtomatizacijo potrebuje dostop do vaših podatkov
• Druge storitve vam pošiljajo dogodke (webhooks)
• Delo delite med ekipo za frontend in ekipo za backend

REST je najpogostejši slog, vendar ni edini. REST proti GraphQL pojasni, kdaj se bolj splača ena prilagodljiva poizvedovalna točka.

Najprej zasnova: viri in poti

Zapišite samostalnike iz svoje aplikacije in to, kaj ljudje z njimi počnejo. Za preprosto aplikacijo za rezervacije:

To se preslika na ustvarjanje, branje, posodabljanje in brisanje; glejte kaj je CRUD. Vredna so naslednja pravila:

• Množinski samostalniki, brez glagolov v URL-jih: /bookings, ne /getBookings.
• Gnezdite samo eno raven, kadar to jasno pokaže lastništvo: /bookings/{id}/notes.
• Dejanja, ki niso CRUD, so lahko podvir: POST /bookings/{id}/cancel je jasnejše kot skrivnostni PATCH.
• Dosledno poimenovanje polj, na primer created_at povsod.

Statusne kode in napake

Uporabljajte standardne kode HTTP, da odjemalci vedo, kaj se je zgodilo, ne da bi morali razčlenjevati besedilo:

Vračajte napake v eni dosledni obliki JSON, na primer {"error": {"code": "slot_taken", "message": "Ta termin ni več na voljo."}}, in v odgovorih nikoli ne vključujte sledi skladovnika ali napak baze podatkov.

Možnosti in kompromisi

Korak za korakom

1. Popišite vire in poti kot zgoraj, vključno s tem, kdo lahko kliče posamezno pot.
2. Modelirajte podatke v bazi s polji in razmerji, ki jih potrebujete.
3. Najprej zgradite poti za branje, nato ustvarjanje, posodabljanje in brisanje.
4. Validirajte vnos pri vsakem pisanju s knjižnico za sheme: obvezna polja, tipi, dolžine, dovoljene vrednosti. Zavrnite neznana polja.
5. Dodajte avtentikacijo, nato avtorizacijo za vsak zapis: nalaganje /bookings/42 mora preveriti, ali rezervacija 42 pripada klicatelju, ne le, da je nekdo prijavljen.
6. Razdelite vsak seznam na strani in omejite velikost strani.
7. Omejite število zahtevkov za prijavo in drage poti. Glejte omejevanje zahtevkov.
8. Nastavite CORS samo, če morajo brskalniki z drugih domen klicati API, in dovoljene izvore naštejte izrecno. Kako popraviti napake CORS pojasni napake, ki jih boste videli.
9. Napišite dokumentacijo in teste za vsako pot, vključno z primeri napak.
10. Objavite s skrivnostmi v okoljskih spremenljivkah, HTTPS, dnevniki in preverjanjem delovanja.

Poizvedbe za AI graditelja

Za začetno postavitev:

Ustvari REST API za rezervacije s temi potmi: GET /api/health, GET /api/bookings (s paginacijo, največ 50 na stran), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Podatke shranjuj v našo bazo. Telesa zahtevkov validiraj s knjižnico za sheme in zavrni neznana polja. Napake vračaj kot JSON {"error": {"code", "message"}} s pravilnimi statusnimi kodami (400, 401, 403, 404, 409). Skrivnosti hrani v okoljskih spremenljivkah.

Varnost:

Za vse poti za rezervacije zahtevaj prijavo. Pri vsakem branju, posodobitvi in brisanju na strežniku preveri, ali rezervacija pripada trenutnemu uporabniku; če ne, vrni 404. Iz telesa zahtevka nikoli ne sprejemaj ID-jev uporabnikov ali vlog. Omeji POST /api/bookings na 20 zahtevkov na minuto na uporabnika. Napake beleži na strežniku, ne vračaj sledi skladovnika.

Dokumentacija:

Napiši opis teh poti v OpenAPI in kratek README s primeri zahtevkov in odgovorov za vsako pot.

Testiranje API-ja

Preizkušajte z zunanje strani frontenda, ker bodo to počeli napadalci:

• Vsaka pot deluje z veljavnim vnosom in vrne dokumentirano obliko ter kodo
• Manjkajoča ali neveljavna polja vrnejo 400 z jasnim sporočilom
• Brez žetona vsaka zaščitena pot vrne 401
• Uporabnik A, ki zahteva zapis uporabnika B prek ID-ja, dobi 404 ali 403
• Seznami so razdeljeni na strani, velik limit pa je omejen
• Podvojeni ali konfliktni vnosi vrnejo 409, ne 500
• Omejitve zahtevkov vrnejo 429
• Odgovori o napakah ne vsebujejo sledi skladovnika, SQL-a ali skrivnosti
• CORS dovoljuje samo izvore, ki jih želite

Pogoste napake

• Preverjanje prijave, a ne lastništva. Najpogostejša luknja v API-jih: kateri koli prijavljeni uporabnik lahko prebere kateri koli zapis tako, da spremeni ID.
• Zaupanje odjemalcu. Cene, vloge in ID-ji uporabnikov iz telesa zahtevka se lahko spremenijo.
• Vračanje celotnih vrstic baze. Zgoščene vrednosti gesel in notranja polja uhajajo. Izberite, kaj vsak odgovor vključuje.
• Neomejeni seznami. Ena zahteva za vse zapise lahko upočasni celotno aplikacijo.
• 200 OK z napako v sporočilu. Odjemalci in nadzor ne morejo ugotoviti, da je šlo narobe.
• CORS nastavljen tako, da dovoli vse, pri API-ju, ki uporablja piškotke.
• Brez preverjanja delovanja ali dnevnikov, zato za izpade izvete od uporabnikov.

Za širši pregled pred zagonom glejte varnostni kontrolni seznam za aplikacije, zgrajene z AI.

Gradnja REST API-ja v Mythexu

V Mythexu lahko API zahtevate kot del aplikacije ali kot samostojno storitev. Recept v dokumentaciji REST API backend ima začetni poziv: navedite ogrodje in poti, zahtevajte jasne napake v JSON-u, skrivnosti hranite v okoljskih spremenljivkah in vključite Dockerfile. Kontejnerski backendi v Node, Pythonu, C#, Javi in drugih se objavijo prek Dockerfile-a, Mythex pa poskrbi za objavo iz Publish (API backendi). Projekt lahko vzporedno poganja spletno stran in API strežnik, med njima pa lahko preklapljate v predogledu. Skrivnosti shranite kot skrivnosti projekta, če API potrebuje bazo, pa jo zahtevajte v klepetu. Za načrtovana opravila okoli API-ja glejte kako zaganjati ozadinska opravila.

Vprašanja