Kaip sukurti REST API: dizainas, saugumas ir diegimas

Norint sukurti REST API, išvardykite išteklius, kuriuos valdo jūsų programa (vartotojai, užsakymai, rezervacijos), kiekvienam priskirkite URL, pavyzdžiui /orders ir /orders/{id}, o veiksmams naudokite HTTP metodus: GET skaityti, POST kurti, PATCH atnaujinti, DELETE pašalinti. Grąžinkite JSON su prasmingais būsenos kodais, validuokite kiekvieną įvestį, reikalaukite autentifikacijos ir leidimų tikrinimo kiekvienam įrašui serveryje, o sąrašus puslapiuokite. Tada dokumentuokite galutinius taškus ir diegite API už HTTPS.

Šiame vadove aptariami dizaino sprendimai, pavyzdinis maršrutų rinkinys, užduotys AI programų kūrimo įrankiui ir klaidos, dėl kurių atsiranda saugumo spragos. Jei API jums nauji, pradėkite nuo kas yra API.

Kada jums reikia REST API

• Jūsų web sąsajai reikia išsaugoti ir gauti duomenis iš serverio
• Mobiliajai programai, partneriui ar automatizavimo įrankiui reikia prieigos prie jūsų duomenų
• Kitos paslaugos siunčia jums įvykius (webhook'ai)
• Darbą dalijatės tarp sąsajos ir backend komandų

REST yra dažniausias stilius, bet ne vienintelis. REST vs GraphQL paaiškina, kada geriau tinka viena lanksti užklausų galutinis taškas.

Pirma dizainas: ištekliai ir maršrutai

Surašykite savo programos daiktavardžius ir tai, ką su jais daro žmonės. Paprastai rezervacijų programai:

Šie maršrutai atitinka kurti, skaityti, atnaujinti ir trinti; žr. kas yra CRUD. Verta laikytis šių taisyklių:

• URL'uose – daiktavardžiai daugiskaita, be veiksmažodžių: /bookings, o ne /getBookings.
• Įdėkite tik vieną lygį, kai tai aiškiau parodo priklausomybę: /bookings/{id}/notes.
• Veiksmai, kurie nėra CRUD, gali būti poišteklius: POST /bookings/{id}/cancel aiškesnis nei neaiškus PATCH.
• Nuoseklūs laukų pavadinimai, pavyzdžiui created_at visur.

Būsenos kodai ir klaidos

Naudokite standartinius HTTP kodus, kad klientai suprastų, kas įvyko, neanalizuodami teksto:

Grąžinkite klaidas vienu nuosekliu JSON formatu, pavyzdžiui {"error": {"code": "slot_taken", "message": "Tas laikas nebeprieinamas."}}, ir niekada neįtraukite į atsakymus steko pėdsakų ar duomenų bazės klaidų.

Parinktys ir kompromisai

Žingsnis po žingsnio

1. Išvardykite išteklius ir maršrutus kaip aukščiau, įskaitant, kas gali kiekvieną iškviesti.
2. Modeliuokite duomenis savo duomenų bazėje su reikalingais laukais ir ryšiais.
3. Pirma kurkite skaitymo maršrutus, tada kūrimo, atnaujinimo ir trynimo.
4. Validuokite įvestį kiekviename rašymo maršrute su schemos biblioteka: privalomi laukai, tipai, ilgiai, leistinos reikšmės. Atmeskite nežinomus laukus.
5. Pridėkite autentifikaciją, tada leidimus kiekvienam įrašui: atidarant /bookings/42 reikia tikrinti, ar rezervacija 42 priklauso iškvietėjui, o ne tik tai, ar kas nors yra prisijungęs.
6. Puslapiuokite kiekvieną sąrašą ir apribokite puslapio dydį.
7. Ribokite užklausas prisijungimui ir brangiems maršrutams. Žr. užklausų ribojimas.
8. Konfigūruokite CORS tik tuo atveju, jei naršyklės kitose svetainėse turi kviesti API, ir aiškiai įrašykite tas kilmes. Kaip ištaisyti CORS klaidas paaiškina klaidas, kurias pamatysite.
9. Parašykite dokumentaciją ir testus kiekvienam maršrutui, įskaitant nesėkmės atvejus.
10. Diegite su paslaptimis aplinkos kintamuosiuose, HTTPS, žurnalais ir patikros maršrutu.

Užduotys jūsų AI kūrimo įrankiui

Sukurti karkasą:

Sukurk bookings REST API su šiais maršrutais: GET /api/health, GET /api/bookings (puslapiuojama, daugiausia 50 įrašų puslapyje), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Saugok duomenis mūsų duomenų bazėje. Patikrink užklausų turinį schemos biblioteka ir atmesk nežinomus laukus. Klaidas grąžink kaip JSON {"error": {"code", "message"}} su teisingais būsenos kodais (400, 401, 403, 404, 409). Paslaptis laikyk aplinkos kintamuosiuose.

Saugumas:

Reikalauk prisijungimo kiekviename bookings maršrute. Kiekvieno skaitymo, atnaujinimo ir trynimo metu serveryje patikrink, ar rezervacija priklauso dabartiniam vartotojui; jei ne, grąžink 404. Niekada nepriimk vartotojo ID ar vaidmenų iš užklausos turinio. Riboki POST /api/bookings iki 20 per minutę vienam vartotojui. Serveryje rašyk klaidų žurnalus, bet negrąžink steko pėdsakų.

Dokumentacija:

Parašyk šių maršrutų OpenAPI aprašymą ir trumpą README su pavyzdinėmis užklausomis ir atsakymais kiekvienam maršrutui.

API testavimas

Testuokite iš išorės, nes taip elgsis ir piktavaliai:

• Kiekvienas maršrutas veikia su tinkama įvestimi ir grąžina dokumentuotą formatą bei kodą
• Trūkstami ar neteisingi laukai grąžina 400 su aiškia žinute
• Be tokeno kiekviename apsaugotame maršrute grąžinamas 401
• Vartotojas A, prašydamas vartotojo B įrašo pagal ID, gauna 404 arba 403
• Sąrašai puslapiuojami; labai didelis limit yra apribojamas
• Dublikatiniai ar konfliktuojantys kūrimai grąžina 409, o ne 500
• Užklausų ribos grąžina 429
• Klaidų atsakymuose nėra steko pėdsakų, SQL ar paslapčių
• CORS leidžia tik numatytas kilmes

Dažnos klaidos

• Tikrinamas prisijungimas, bet ne nuosavybė. Dažniausia API spraga: bet kuris prisijungęs vartotojas gali perskaityti bet kurį įrašą pakeisdamas ID.
• Pasitikima klientu. Kainas, vaidmenis ir vartotojų ID iš užklausos turinio galima pakeisti.
• Grąžinamos visos duomenų bazės eilutės. Slaptažodžių maišos ir vidiniai laukai nutekėja. Pasirinkite, ką kiekvienas atsakymas turi.
• Neribotos sąrašai. Viena užklausa visiems įrašams gali sulėtinti visą programą.
• 200 OK su klaida viduje. Klientai ir stebėjimas nemato, kad įvyko klaida.
• CORS nustatytas leisti viską API, kuris naudoja slapukus.
• Nėra patikros maršruto ar žurnalų, todėl apie gedimus sužinote iš vartotojų.

Platesniam prieš paleidimą atliekamam patikrinimui žr. saugumo kontrolinį sąrašą DI sukurtoms programoms.

REST API kūrimas Mythex

Mythex galite paprašyti API kaip programos dalies arba kaip atskiros paslaugos. Docs receptas REST API backend turi pradinę užklausą: nurodykite karkasą ir maršrutus, paprašykite aiškių JSON klaidų, laikykite paslaptis aplinkos kintamuosiuose ir įtraukite Dockerfile. Konteinerių backend'ai Node, Python, C#, Java ir kitomis kalbomis publikuojami per Dockerfile, o diegimą iš Publish atlieka Mythex (API backend'ai). Projektas gali veikti kaip svetainė ir API serveris kartu, o peržiūroje tarp jų galite perjungti. Paslaptis saugokite kaip projekto paslaptis, o jei API reikia duomenų bazės, paprašykite jos pokalbyje. Apie suplanuotus darbus aplink API žr. kaip paleisti fono užduotis.

Klausimai