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.

Selles juhendis on disainiotsused, näidisstruktuur marsruutidest, promptid AI rakenduste ehitajale ning vead, mis tekitavad turvaaukusid. Kui API-d on teile uued, alustage sellest, 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, kuid mitte ainus. REST vs GraphQL selgitab, millal sobib paremini üks paindlik päringute lõpp-punkt.

Esmalt disain: ressursid ja marsruudid

Kirjutage üles oma rakenduse nimisõnad ja see, mida inimesed nendega teevad. Lihtsa broneerimisrakenduse näide:

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}/cancel on selgem kui salapärane PATCH.
• Ühtne nimetamine väljadel, näiteks created_at kõikjal.

Olekukoodid ja vead

Kasutage standardseid HTTP koode, et kliendid saaksid aru, mis juhtus, ilma teksti parsimata:

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

Samm-sammult

1. Loetlege ressursid ja marsruudid nagu ülal, sh see, kes iga marsruuti tohib kutsuda.
2. Modelleerige andmed oma andmebaasis vajalike väljade ja seostega.
3. Ehitage esmalt lugemise marsruudid, seejärel loomine, uuendamine ja kustutamine.
4. Valideerige sisend iga kirjutamise puhul skeemiteegi abil: kohustuslikud väljad, tüübid, pikkused, lubatud väärtused. Lükake tundmatud väljad tagasi.
5. Lisage autentimine, seejärel õiguste kontroll kirje kohta: marsruudi /bookings/42 laadimisel tuleb kontrollida, et broneering 42 kuulub kutsujale, mitte ainult seda, et keegi on sisse logitud.
6. Jagage iga loend lehekülgedeks ja piirake lehe suurust.
7. Piirake päringute arvu sisselogimisel ja kulukatel marsruutidel. Vt päringupiirangud.
8. 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.
9. Kirjutage dokumentatsioon ja testid iga marsruudi kohta, sh tõrkejuhtumid.
10. 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 limit on 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 OK koos 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

Mythexis saate paluda API-d osana oma rakendusest või eraldi teenusena. Dokumentatsiooni retsept REST API backend sisaldab algpromptit: nimetage raamistik ja marsruudid, paluge selgeid JSON-vigu, hoidke saladused keskkonnamuutujates ja lisage Dockerfile. Konteineritel põhinevad backendid Node, Python, C#, Java ja teistes keeltes avaldatakse Dockerfile’i kaudu ning Mythex haldab juurutamist menüüst Publish (API backendid). Projekt võib käitada kõrvuti veebilehte ja API serverit ning eelvaates saate neid vahetada. Hoidke võtmed projekti saladustena ja kui API vajab andmebaasi, paluge see vestluses. Taustatööde ümber oma API-ga vt kuidas käivitada taustatöid.

Küsimused