Kako izraditi REST API: dizajn, sigurnost i objava

Za izradu REST API-ja popišite resurse kojima vaša aplikacija upravlja (korisnike, narudžbe, rezervacije), dodijelite svakom URL, primjerice /orders i /orders/{id}, i koristite HTTP metode za radnje: GET za čitanje, POST za stvaranje, PATCH za ažuriranje i DELETE za brisanje. Vraćajte JSON sa smislenim statusnim kodovima, validirajte svaki unos, zahtijevajte autentifikaciju i provjere dopuštenja za svaki zapis na poslužitelju te stranicirajte popise. Zatim dokumentirajte krajnje točke i objavite API iza HTTPS-a.

Ovaj vodič obuhvaća odluke o dizajnu, primjer skupa ruta, upute za AI alat za izradu aplikacija i pogreške koje uzrokuju sigurnosne rupe. Ako su vam API-ji novi, počnite s što je API.

Kada su vam potrebni REST API-ji

• Vaš web frontend mora spremati i učitavati podatke s poslužitelja
• Mobilnoj aplikaciji, partneru ili alatu za automatizaciju treba pristup vašim podacima
• Drugi servisi šalju vam događaje (webhookovi)
• Posao dijelite između frontend i backend tima

REST je najčešći stil, ali nije jedini. REST naspram GraphQL-a objašnjava kada je jedna fleksibilna krajnja točka za upite bolji izbor.

Prvo dizajn: resursi i rute

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

Ove rute odgovaraju stvaranju, čitanju, ažuriranju i brisanju; pogledajte što je CRUD. Konvencije koje vrijedi slijediti:

• Množina imenica bez glagola u URL-ovima: /bookings, a ne /getBookings.
• Ugnježđivanje samo jedne razine kada to razjašnjava vlasništvo: /bookings/{id}/notes.
• Radnje koje nisu CRUD mogu biti podresursi: POST /bookings/{id}/cancel je jasnije od zagonetnog PATCH-a.
• Dosljeni nazivi polja, primjerice created_at svuda.

Statusni kodovi i greške

Koristite standardne HTTP kodove da klijenti znaju što se dogodilo bez raščlanjivanja teksta:

Vraćajte greške u jednom dosljednom JSON obliku, primjerice {"error": {"code": "slot_taken", "message": "Taj termin više nije dostupan."}}, i nikada ne uključujte stack trace ili pogreške baze podataka u odgovore.

Mogućnosti i kompromisi

Korak po korak

1. Popišite resurse i rute kao gore, uključujući tko smije pozvati koju.
2. Modelirajte podatke u bazi s poljima i vezama koje trebate.
3. Prvo izradite rute za čitanje, zatim stvaranje, ažuriranje i brisanje.
4. Validirajte unos na svakom zapisu pomoću biblioteke sheme: obavezna polja, tipovi, duljine, dopuštene vrijednosti. Odbijte nepoznata polja.
5. Dodajte autentifikaciju, zatim autorizaciju po zapisu: dohvat /bookings/42 mora provjeriti pripada li rezervacija 42 pozivatelju, a ne samo je li netko prijavljen.
6. Stranicirajte svaki popis i ograničite veličinu stranice.
7. Ograničite broj zahtjeva za prijavu i skupe rute. Pogledajte ograničavanje broja zahtjeva.
8. Konfigurirajte CORS samo ako preglednici na drugim domenama moraju zvati API, i izričito 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 s tajnim podacima u varijablama okruženja, HTTPS-om, zapisnicima i provjerom stanja.

Upute za AI alat za izradu aplikacija

Skela:

Napravi REST API za rezervacije s ovim rutama: GET /api/health, GET /api/bookings (stranicirano, najviše 50 po stranici), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Spremaj podatke u našu bazu. Validiraj tijela zahtjeva pomoću biblioteke sheme i odbij nepoznata polja. Vraćaj JSON greške kao {"error": {"code", "message"}} s ispravnim statusnim kodovima (400, 401, 403, 404, 409). Tajne čuvaj u varijablama okruženja.

Sigurnost:

Zahtijevaj prijavu na svakoj ruti za rezervacije. Kod svakog čitanja, ažuriranja i brisanja na poslužitelju provjeri pripada li rezervacija trenutnom korisniku; ako ne pripada, vrati 404. Nikada ne prihvaćaj ID-jeve korisnika ili uloge iz zahtjeva. Ograniči POST /api/bookings na 20 po minuti po korisniku. Greške bilježi na poslužitelju bez vraćanja stack traceova.

Dokumentacija:

Napiši OpenAPI opis ovih ruta i kratak README s primjerima zahtjeva i odgovora za svaku rutu.

Testiranje API-ja

Testirajte izvana, mimo frontenda, jer će to raditi napadači:

• Svaka ruta radi s ispravnim unosom i vraća dokumentirani 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 dobiva 404 ili 403
• Popisi su stranicirani; ogromni limit je ograničen
• Duplikati ili sukobi pri stvaranju vraćaju 409, a ne 500
• Ograničenja broja zahtjeva vraćaju 429
• Odgovori o greškama ne sadrže stack trace, SQL ili tajne podatke
• CORS dopušta samo namjeravane izvore

Česte pogreške

• Provjera prijave, ali ne vlasništva. Najčešća rupa u API-ju: bilo koji prijavljeni korisnik može čitati bilo koji zapis promjenom ID-ja.
• Vjerovanje klijentu. Cijene, uloge i ID-jevi korisnika iz tijela zahtjeva mogu se mijenjati.
• Vraćanje cijelih redaka baze. Hashevi lozinki i interna polja curu. Odaberite što svaki odgovor uključuje.
• Neograničeni popisi. Jedan zahtjev za svim zapisima može usporiti cijelu aplikaciju.
• 200 OK s porukom o grešci u tijelu. Klijenti i praćenje ne mogu znati da je neuspjelo.
• CORS postavljen da dopušta sve na API-ju koji koristi kolačiće.
• Nema provjere stanja ni zapisnika, pa za prekide saznajete od korisnika.

Za širu provjeru prije lansiranja pogledajte kontrolnu listu sigurnosti za aplikacije izrađene AI-jem.

Izrada REST API-ja u Mythexu

Mythex možete zamoliti za API kao dio aplikacije ili kao zasebnu uslugu. Recept u dokumentaciji REST API backend sadrži početni upit: navedite okvir i rute, zatražite jasne JSON greške, čuvajte tajne podatke u varijablama okruženja i uključite Dockerfile. Container backendi u Nodeu, Pythonu, C#-u, Javi i drugim jezicima objavljuju se putem Dockerfilea, a Mythex se brine o objavi iz Publish (API backendi). Projekt može imati web stranicu i API poslužitelj jedno uz drugo te se između njih prebacujete u pregledu. Tajne ključeve spremite kao tajne projekta, a ako API treba bazu podataka, zatražite je u chatu. Za zakazane poslove oko vašeg API-ja pogledajte kako pokrenuti pozadinske poslove.

Pitanja