Kuidas ehitada REST API: disain, turvalisus ja juurutamine
REST API ehitamiseks loetlege oma rakenduses hallatavad ressursid (kasutajad, tellimused, broneeringud), andke igaühele URL, näiteks /orders ja /orders/{id}, ning kasutage tegevuste jaoks HTTP meetodeid: GET lugemiseks, POST loomiseks, PATCH uuendamiseks ja DELETE eemaldamiseks. Tagastage JSON koos sisukate olekukoodidega, valideerige iga sisend, nõudke autentimist ja kontrollige serveris õigusi iga kirje kohta eraldi ning jagage nimekirjad lehekülgedeks. Seejärel dokumenteerige lõpp-punktid ja juurutage API HTTPS-i taga.
See juhend käsitleb disainiotsuseid, töötavat marsruutide komplekti, AI rakendusehitaja nagu Mythex jaoks mõeldud käske ja vigu, mis tekitavad turvaaugud. Kui API-d on sulle uued, alusta mis on API.
Millal vajate REST API-d
- Teie veebiliides peab andmeid serverisse salvestama ja sealt laadima
- Mobiilirakendus, partner või automatiseerimise tööriist vajab ligipääsu teie andmetele
- Teised teenused saadavad teile sündmusi (webhookid)
- Töö jaguneb frontendi ja backendi meeskonna vahel
REST on kõige levinum stiil, aga mitte ainus. REST vs GraphQL selgitab, millal üks paindlik päringu-lõpp-punkt sobib paremini.
Esmalt disain: ressursid ja marsruudid
Kirjutage üles oma rakenduse nimisõnad ja see, mida inimesed nendega teevad. Lihtsa broneerimisrakenduse näide:
| Meetod | Marsruut | Mida teeb | Õnnestumise kood |
|---|---|---|---|
GET | /api/bookings | Kutsuja broneeringute loend (lehekülgedeks jaotatud) | 200 |
POST | /api/bookings | Loo broneering | 201 |
GET | /api/bookings/{id} | Ühe broneeringu vaatamine | 200 |
PATCH | /api/bookings/{id} | Muuda mõningaid välju | 200 |
DELETE | /api/bookings/{id} | Tühista broneering | 204 |
GET | /api/health | Tervisekontroll jälgimiseks | 200 |
Need vastavad loomise, lugemise, uuendamise ja kustutamise toimingutele (CRUD); vt mis on CRUD. Soovitatavad reeglid:
- Mitmuse nimisõnad, ilma tegusõnadeta URL-ides:
/bookings, mitte/getBookings. - Pesastage ainult ühe taseme võrra, kui see selgitab omandisuhet:
/bookings/{id}/notes. - Tegevused, mis pole CRUD, võivad olla alamressursid:
POST /bookings/{id}/cancelon selgem kui salapärane PATCH. - Ühtne nimetamine väljadel, näiteks
created_atkõikjal.
Olekukoodid ja vead
Kasutage standardseid HTTP koode, et kliendid saaksid aru, mis juhtus, ilma teksti parsimata:
| Kood | Tähendus | Kasuta, kui |
|---|---|---|
| 200 | OK | Edukas lugemine või uuendamine |
| 201 | Created | POST lõi midagi |
| 204 | No Content | Edu, aga tagastada pole midagi |
| 400 | Bad Request | Sisend ei läbinud valideerimist |
| 401 | Unauthorized | Pole sisse logitud või vale token |
| 403 | Forbidden | Sisse logitud, kuid pole luba |
| 404 | Not Found | Ei eksisteeri või kutsuja ei tohi teada, et see eksisteerib |
| 409 | Conflict | Duplikaat või aeg on juba broneeritud |
| 429 | Too Many Requests | Päringupiirang on täis |
| 500 | Server Error | Midagi läks teie poolel katki |
Tagastage vead ühtses JSON-kujus, näiteks {"error": {"code": "slot_taken", "message": "See aeg ei ole enam saadaval."}}, ja ärge kunagi lisage vastustesse veapinu ega andmebaasi vigu.
Valikud ja kompromissid
| Otsus | Lihtne valik | Alternatiiv |
|---|---|---|
| Kus API asub | API-marsruudid teie veebiraamistikus | Eraldi API-teenus, kasulik mitme kliendi või teistsuguse keele korral |
| Autentimine | Seansiküpsised enda veebirakendusele | Tokenid (bearer-tokenid või API-võtmed) mobiilirakendustele ja kolmandatele osapooltele |
| Lehekülgede jaotus | ?page=2&limit=20 | Kursoripõhine (?after=...), stabiilsem suurte ja muutuvate loendite puhul |
| Versioonihaldus | Pole, kuni teil pole väliseid kasutajaid | /v1/ teel, kui teised sõltuvad juba API-st |
| Dokumentatsioon | README marsruutide loendiga | OpenAPI kirjeldus, mille tööriistad saavad teisendada interaktiivseks dokumentatsiooniks ja kliendikoodiks |
Samm-sammult
- Loetlege ressursid ja marsruudid nagu ülal, sh see, kes iga marsruuti tohib kutsuda.
- Modelleerige andmed oma andmebaasis vajalike väljade ja seostega.
- Ehitage esmalt lugemise marsruudid, seejärel loomine, uuendamine ja kustutamine.
- Valideerige sisend iga kirjutamise puhul skeemiteegi abil: kohustuslikud väljad, tüübid, pikkused, lubatud väärtused. Lükake tundmatud väljad tagasi.
- Lisage autentimine, seejärel õiguste kontroll kirje kohta: marsruudi
/bookings/42laadimisel tuleb kontrollida, et broneering 42 kuulub kutsujale, mitte ainult seda, et keegi on sisse logitud. - Jagage iga loend lehekülgedeks ja piirake lehe suurust.
- Piirake päringute arvu sisselogimisel ja kulukatel marsruutidel. Vt päringupiirangud.
- Seadistage CORS ainult siis, kui teiste domeenide brauserid peavad API-d kutsuma, ja lubage need päritolud selgesõnaliselt. Kuidas parandada CORS-i vigu selgitab vigu, mida näete.
- Kirjutage dokumentatsioon ja testid iga marsruudi kohta, sh tõrkejuhtumid.
- Juurutage nii, et saladused on keskkonnamuutujates, ühendus on HTTPS-i kaudu ning olemas on logid ja tervisekontroll.
Promptid AI ehitajale
Skelett:
Loo broneeringute REST API järgmiste marsruutidega: GET /api/health, GET /api/bookings (lehekülgedeks jaotatud, maksimaalselt 50 lehe kohta), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Salvesta andmed meie andmebaasi. Valideeri päringukehad skeemiteegiga ja lükka tundmatud väljad tagasi. Tagasta JSON-vead kujul {"error": {"code", "message"}} õigete olekukoodidega (400, 401, 403, 404, 409). Hoia saladused keskkonnamuutujates.
Turvalisus:
Nõua sisselogimist igal broneeringute marsruudil. Iga lugemise, uuendamise ja kustutamise puhul kontrolli serveris, et broneering kuulub praegusele kasutajale; kui ei kuulu, tagasta 404. Ära kunagi võta kasutaja ID-sid ega rolle päringu kehast vastu. Piira POST /api/bookings 20 päringuni minutis kasutaja kohta. Logi vead serveris, ilma veapinuta vastustes.
Dokumentatsioon:
Kirjelda neid marsruute OpenAPI kirjelduses ja kirjuta lühike README, kus on iga marsruudi näidispäringud ja -vastused.
API testimine
Testige väljastpoolt frontendi, sest ründajad teevad seda:
- Iga marsruut töötab korrektse sisendiga ja tagastab dokumenteeritud kuju ja koodi
- Puuduvad või vigased väljad annavad 400 koos selge sõnumiga
- Tokenita päring annab 401 igal kaitstud marsruudil
- Kasutaja A päring kasutaja B kirjele ID järgi annab 404 või 403
- Loendid on lehekülgedeks jaotatud; suur
limiton piiratud - Duplikaat- või konfliktsed loomised annavad 409, mitte 500
- Päringupiirangud annavad 429
- Vigade vastused ei sisalda veapinu, SQL-i ega saladusi
- CORS lubab ainult soovitud päritolusid
Levinud vead
- Sisselogimise kontrollimine ilma omandi kontrollita. Kõige levinum API-auk: iga sisselogitud kasutaja saab lugeda mis tahes kirjet, kui muudab ID-d.
- Kliendi usaldamine. Hinnad, rollid ja kasutaja ID-d päringu kehast on muudetavad.
- Terve andmebaasirea tagastamine. Paroolide räsid ja sisemised väljad lekivad. Valige, mida iga vastus sisaldab.
- Piiramata loendid. Iga kirje päring võib aeglustada kogu rakendust.
200 OKkoos veateatega sees. Kliendid ja jälgimine ei saa aru, et see ebaõnnestus.- CORS seatud lubama kõike API puhul, mis kasutab küpsiseid.
- Tervisekontrolli ega logisid ei ole, nii et katkestustest saate teada kasutajatelt.
Laiemaks eeltootmise kontrolliks vt turvakontrollnimekirja AI-ehitatud rakendustele.
REST API ehitamine Mythexis
Mythexilt saad API-d paluda kas osana oma rakendusest või eraldi teenusena. Dokumentatsiooni retsept REST API taust sisaldab alustavat käsku: nimeta raamistik ja marsruudid, palu selgeid JSON-vigu, hoia saladused keskkonnamuutujates ning lisa Dockerfile. Konteinerpõhised taustad Node, Python, C#, Java ja teistes keeltes avalduvad Dockerfile'i kaudu ning Mythex tegeleb juurutusega avaldamise käigus (API taustad). Projekt võib käitada veebilehte ja API serverit kõrvuti ning sa saad eelvaates nende vahel vahetada. Hoia võtmed projekti saladustena ning kui API vajab andmebaasi, palu see vestluses: iga projekt võib saada oma Postgres andmebaasi, mis sisaldub igal plaanil. Agent saab API-d sinu eest testida ning Pro-plaanil saad koodi ise redaktoris ja terminalis muuta või hoida seda kahesuunalises GitHubi sünkroonis. Taustatöödeks oma API ümber vaata kuidas käivitada taustatöid.
Küsimused
Mis on REST API?
REST API on viis, kuidas programmid saavad teie rakenduse andmetega HTTP kaudu töötada. Iga andmetüüp on ressurss oma URL-iga, näiteks /orders, ja selle kallal toimivad standardsed meetodid: GET lugemiseks, POST loomiseks, PATCH või PUT uuendamiseks ja DELETE eemaldamiseks. Andmeid saadetakse tavaliselt JSON-vormingus.
Mis keeles peaksin REST API-d ehitama?
Kasuta seda, mida sina või su meeskond suudab hooldada. Node.js koos Expressi või Fastifyga, Python koos FastAPI-ga ning C# või Java raamistikud töötavad kõik hästi. Marsruutide, olekukoodide, valideerimise ja autentimise disainireeglid on olulisemad kui keel. Mythex käitab API-sid Node, Python, Java, C# või millegi muu peal, mis töötab Dockerfile'ist veebiserverina, nii et võid valida selle, mida tead.
Kuidas REST API-d turvata?
Nõudke autentimist igal marsruudil, mis pole avalik, kontrollige serveris, kas kutsuja tohib just seda konkreetset kirjet kasutada, valideerige kogu sisend, kasutage HTTPS-i, piirake päringute arvu ja hoidke saladused keskkonnamuutujates. Ärge kunagi usaldage kliendi saadetud ID-sid ega rolle.
Kas REST API jaoks on vaja eraldi backend’i?
Mitte alati. Raamistikud nagu Next.js saavad serveerida API-marsruute lehtede kõrval. Eraldi API-teenus on mõistlik, kui seda kasutavad mitu klienti (veeb, mobiil, partnerid) või kui see vajab oma keelt või skaleerimist. Mythexis saavad veebileht ja API elada samas projektis ning avalduda koos.