Kā izveidot REST API: dizains, drošība un izvietošana

Lai izveidotu REST API, uzskaitiet resursus, ko jūsu lietotne pārvalda (lietotāji, pasūtījumi, rezervācijas), katram piešķiriet URL, piemēram, /orders un /orders/{id}, un darbībām izmantojiet HTTP metodes: GET lasīšanai, POST izveidei, PATCH atjaunināšanai, DELETE dzēšanai. Atgrieziet JSON ar jēgpilniem statusa kodiem, validējiet katru ievadi, prasiet autentifikāciju un pārbaudiet tiesības uz katru ierakstu serverī, kā arī lapojiet sarakstus. Pēc tam dokumentējiet galapunktus un izvietojiet API aiz HTTPS.

Šajā ceļvedī ir aplūkoti dizaina lēmumi, piemērs ar maršrutiem, uzvednes AI lietotņu veidotājam un kļūdas, kas rada drošības caurumus. Ja API ir jauns jēdziens, sāciet ar ko nozīmē API.

Kad jums vajag REST API

• Jūsu tīmekļa interfeisam jāsaglabā un jāielādē dati no servera
• Mobilajai lietotnei, partnerim vai automatizācijas rīkam nepieciešama piekļuve jūsu datiem
• Citi servisi jums sūta notikumus (webhook)
• Jūs sadalāt darbu starp frontend un backend komandām

REST ir visbiežāk izmantotais stils, bet ne vienīgais. REST vs GraphQL izskaidro, kad piemērotāks ir viens elastīgs vaicājumu galapunkts.

Vispirms dizains: resursi un maršruti

Uzrakstiet lietotnes lietvārdus un to, ko cilvēki ar tiem dara. Vienkāršai rezervēšanas lietotnei:

Tie atbilst izveidei, lasīšanai, atjaunināšanai un dzēšanai; skatiet kas ir CRUD. Konvencijas, ko vērts ievērot:

• Daudzskaitļa lietvārdi, bez darbības vārdiem URL: /bookings, nevis /getBookings.
• Ligzdojiet tikai vienā līmenī, ja tas skaidro piederību: /bookings/{id}/notes.
• Darbības, kas nav CRUD, var būt apakšresursi: POST /bookings/{id}/cancel ir skaidrāks nekā noslēpumaina PATCH.
• Konsekventi lauku nosaukumi, piemēram, created_at visur.

Statusa kodi un kļūdas

Izmantojiet standarta HTTP kodus, lai klienti zinātu, kas notika, bez teksta parsēšanas:

Atgriežiet kļūdas vienā konsekventā JSON formātā, piemēram, {"error": {"code": "slot_taken", "message": "Šis laiks vairs nav pieejams."}}, un atbildēs nekad neiekļaujiet steka izsekojumus vai datubāzes kļūdas.

Iespējas un kompromisi

Soli pa solim

1. Uzskaitiet resursus un maršrutus kā iepriekš, tostarp to, kas drīkst katru izsaukt.
2. Modelējiet datus datubāzē ar laukiem un saitēm, kas jums vajadzīgas.
3. Vispirms izveidojiet lasīšanas maršrutus, tad izveidi, atjaunināšanu un dzēšanu.
4. Validējiet ievadi katrā rakstīšanas reizē, izmantojot shēmu bibliotēku: obligātie lauki, tipi, garumi, atļautās vērtības. Noraidiet nezināmus laukus.
5. Pievienojiet autentifikāciju, tad autorizāciju katram ierakstam: piekļūstot /bookings/42, jāpārbauda, ka rezervācija 42 pieder izsaucējam, nevis tikai tas, ka kāds ir pieteicies.
6. Lapojiet katru sarakstu un ierobežojiet lapas izmēru.
7. Ierobežojiet pieprasījumus pieteikšanās un dārgiem maršrutiem. Skatiet pieprasījumu ierobežošanu.
8. Konfigurējiet CORS tikai tad, ja pārlūkprogrammām citos domēnos jāizsauc API, un uzskaitiet šos avotus skaidri. Kā labot CORS kļūdas izskaidro kļūdas, ko redzēsiet.
9. Uzrakstiet dokumentāciju un testus katram maršrutam, tostarp kļūmju gadījumiem.
10. Izvietojiet ar noslēpumiem vides mainīgajos, HTTPS, žurnāliem un veselības pārbaudi.

Uzvednes AI veidotājam

Skeleta izveide:

Izveido REST API rezervācijām ar šiem maršrutiem: GET /api/health, GET /api/bookings (lapots, maks. 50 vienā lapā), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Saglabā datus mūsu datubāzē. Validē pieprasījumu pamatus ar shēmu bibliotēku un noraidi nezināmus laukus. Atgriez JSON kļūdas formātā {"error": {"code", "message"}} ar pareiziem statusa kodiem (400, 401, 403, 404, 409). Glabā noslēpumus vides mainīgajos.

Drošība:

Prasi pieteikšanos katrā rezervāciju maršrutā. Katrā lasīšanas, atjaunināšanas un dzēšanas reizē serverī pārbaudi, vai rezervācija pieder pašreizējam lietotājam; ja nepieder, atgriez 404. Nekad nepieņem lietotāju ID vai lomas no pieprasījuma pamatteksta. Ierobežo POST /api/bookings līdz 20 pieprasījumiem minūtē uz lietotāju. Žurnalizē kļūdas serverī, neatgriežot steka izsekojumus.

Dokumentācija:

Uzraksti šo maršrutu OpenAPI aprakstu un īsu README ar piemēriem pieprasījumiem un atbildēm katram maršrutam.

API testēšana

Testējiet no ārpuses, ārpus frontend, jo uzbrucēji to darīs:

• Katrs maršruts darbojas ar derīgu ievadi un atgriež dokumentēto struktūru un kodu
• Trūkstoši vai nederīgi lauki atgriež 400 ar skaidru ziņojumu
• Bez tokena katrs aizsargātais maršruts atgriež 401
• Lietotājs A, pieprasot lietotāja B ierakstu pēc ID, saņem 404 vai 403
• Sarakstiem ir lapošana; liels limit tiek ierobežots
• Dublējoši vai konfliktējoši izveides pieprasījumi atgriež 409, nevis 500
• Pieprasījumu ierobežojumi atgriež 429
• Kļūdu atbildēs nav steka izsekojumu, SQL vai noslēpumu
• CORS atļauj tikai tos avotus, kurus paredzējāt

Biežākās kļūdas

• Pārbaudīt pieteikšanos, bet ne piederību. Visbiežākais API caurums: jebkurš pieteicies lietotājs var nolasīt jebkuru ierakstu, mainot ID.
• Uzticēties klientam. Cenas, lomas un lietotāju ID no pieprasījuma pamatteksta var mainīt.
• Atgriezt veselas datubāzes rindas. Paroļu jaucējkodi un iekšējie lauki noplūst. Izvēlieties, ko katra atbilde ietver.
• Neierobežoti saraksti. Viens pieprasījums visiem ierakstiem var palēnināt visu lietotni.
• 200 OK ar kļūdas ziņojumu iekšā. Klienti un uzraudzība nevar saprast, ka tas neizdevās.
• CORS iestatīts uz atļaut visu API, kas izmanto sīkfailus.
• Nav veselības pārbaudes vai žurnālu, tāpēc par atteicēm uzzināsiet no lietotājiem.

Plašākai pirms palaišanas pārbaudei skatiet drošības kontrolsarakstu AI veidotām lietotnēm.

REST API veidošana Mythex

Mythex var izveidot API kā daļu no jūsu lietotnes vai kā atsevišķu servisu. Dokumentācijas receptē REST API backend ir sākuma uzvedne: nosauciet ietvaru un maršrutus, prasiet skaidras JSON kļūdas, glabājiet noslēpumus vides mainīgajos un iekļaujiet Dockerfile. Konteineru backend servisi Node, Python, C#, Java un citās valodās tiek publicēti ar Dockerfile, un Mythex apstrādā izvietošanu no Publish (API backend). Projekts var vienlaikus darbināt tīmekļa vietni un API serveri, un starp tiem var pārslēgties priekšskatījumā. Glabājiet atslēgas kā projekta noslēpumus, un, ja API vajag datubāzi, pieprasiet to tērzēšanā. Darbam ar plānotiem uzdevumiem ap API skatiet kā palaist fona darbus.

Jautājumi