REST-rajapinnan rakentaminen: suunnittelu, tietoturva ja julkaisu

REST-rajapinnan rakentamiseksi listaa ensin sovelluksesi resurssit (esimerkiksi käyttäjät, tilaukset, varaukset), anna kullekin URL-osoite, kuten /orders ja /orders/{id}, ja käytä toimintoihin HTTP-metodeja: GET lukuun, POST luontiin, PATCH päivitykseen ja DELETE poistoon. Palauta JSON sopivilla tilakoodeilla, validoi jokainen syöte, vaadi todennus ja tietuekohtaiset oikeustarkistukset palvelimella ja sivuta listat. Dokumentoi sen jälkeen päätepisteet ja julkaise rajapinta HTTPS:n takana.

Tämä opas käy läpi suunnittelupäätökset, toimivan reittijoukon, kehotteet tekoälysovelluksen rakentajalle ja virheet, jotka aiheuttavat tietoturva-aukkoja. Jos rajapinnat ovat sinulle uusia, aloita mikä API on.

Milloin tarvitset REST-rajapinnan

• Verkkokäyttöliittymäsi tarvitsee palvelimen, johon tallentaa ja josta lukea dataa
• Mobiilisovellus, yhteistyökumppani tai automaatiotyökalu tarvitsee pääsyn dataasi
• Muut palvelut lähettävät sinulle tapahtumia (webhookit)
• Frontend- ja backend-työ on jaettu eri tiimeille

REST on yleisin tyyli, mutta ei ainoa. REST vs GraphQL selittää, milloin yksi joustava kyselypäätepiste sopii paremmin.

Suunnittele ensin: resurssit ja reitit

Kirjoita ylös sovelluksesi substantiivit ja se, mitä ihmiset niillä tekevät. Yksinkertaisen varaussovelluksen kohdalla:

Nämä vastaavat luontia, lukua, päivitystä ja poistoa; katso mitä CRUD on. Kannattaa noudattaa näitä käytäntöjä:

• Monikkomuotoiset substantiivit, ei verbejä URL-osoitteissa: /bookings, ei /getBookings.
• Sisäkkäisyys vain yhdelle tasolle, kun se selventää omistajuutta: /bookings/{id}/notes.
• Muut kuin CRUD-toiminnot voivat olla alaresursseja: POST /bookings/{id}/cancel on selkeämpi kuin salaperäinen PATCH.
• Yhdenmukaiset kenttänimet, kuten created_at kaikkialla.

Tilakoodit ja virheet

Käytä standardeja HTTP-koodeja, jotta asiakas tietää, mitä tapahtui, ilman tekstin jäsentämistä:

Palauta virheet yhtenäisessä JSON-muodossa, esimerkiksi {"error": {"code": "slot_taken", "message": "Tuo aika ei ole enää vapaa."}}, äläkä koskaan sisällytä vastauksiin kutsupinoja tai tietokantavirheitä.

Vaihtoehdot ja kompromissit

Vaihe vaiheelta

1. Listaa resurssit ja reitit kuten yllä, mukaan lukien se, kuka kutakin reittiä saa kutsua.
2. Mallinna data tietokannassasi tarvittavilla kentillä ja suhteilla.
3. Rakenna ensin lukureitit, sitten luonti, päivitys ja poisto.
4. Validoi syötteet jokaisessa kirjoituksessa skeemakirjastolla: pakolliset kentät, tyypit, pituudet ja sallitut arvot. Hylkää tuntemattomat kentät.
5. Lisää todennus ja sen jälkeen valtuutus tietuekohtaisesti: reitin /bookings/42 lataus on tarkistettava, että varaus 42 kuuluu kutsujalle, ei vain se, että joku on kirjautunut sisään.
6. Sivuta jokainen lista ja rajoita sivukoko.
7. Rajoita pyyntöjä kirjautumisessa ja raskaissa reiteissä. Katso pyyntörajoitukset.
8. Määritä CORS vain, jos muiden domainien selaimien on kutsuttava rajapintaa, ja listaa nuo lähteet nimenomaisesti. CORS-virheiden korjaaminen selittää virheet, joita kohtaat.
9. Kirjoita dokumentaatio ja testit jokaiselle reitille, myös virhetilanteille.
10. Julkaise niin, että salaisuudet ovat ympäristömuuttujissa, käytössä on HTTPS, lokit ja terveystarkistus.

Kehotteet tekoälysovelluksen rakentajalle

Runko:

Luo REST-rajapinta varauksille näillä reiteillä: GET /api/health, GET /api/bookings (sivutettu, enintään 50 per sivu), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Tallenna data tietokantaan. Validoi pyyntöjen runko skeemakirjastolla ja hylkää tuntemattomat kentät. Palauta JSON-virheet muodossa {"error": {"code", "message"}} oikeilla tilakoodeilla (400, 401, 403, 404, 409). Säilytä salaisuudet ympäristömuuttujissa.

Tietoturva:

Vaadi kirjautuminen jokaiselle varausreitille. Tarkista jokaisessa luvussa, päivityksessä ja poistossa palvelimella, että varaus kuuluu nykyiselle käyttäjälle; palauta 404, jos ei kuulu. Älä koskaan hyväksy käyttäjä-ID:tä tai roolia pyynnön rungosta. Rajoita POST /api/bookings 20 kertaan minuutissa käyttäjää kohden. Kirjaa virheet palvelimelle ilman kutsupinoja vastauksissa.

Dokumentaatio:

Kirjoita näistä reiteistä OpenAPI-kuvaus ja lyhyt README, jossa on esimerkkipyynnöt ja -vastaukset jokaiselle reitille.

Rajapinnan testaaminen

Testaa rajapinta etuosan ulkopuolelta, koska hyökkääjät tekevät niin:

• Jokainen reitti toimii oikealla syötteellä ja palauttaa dokumentoidun muodon ja koodin
• Puuttuvat tai virheelliset kentät palauttavat 400 ja selkeän viestin
• Ilman tunnusta jokainen suojattu reitti palauttaa 401
• Käyttäjä A, joka pyytää käyttäjän B tietuetta ID:n perusteella, saa 404 tai 403
• Listat on sivutettu, ja suuri limit-arvo rajoitetaan
• Kaksoiskappaleet tai ristiriitaiset luonnit palauttavat 409, eivät 500
• Pyyntörajat palauttavat 429
• Virhevastaukset eivät sisällä kutsupinoja, SQL:ää tai salaisuuksia
• CORS sallii vain aiotut lähteet

Yleisimmät virheet

• Kirjautumisen tarkistaminen, mutta ei omistajuuden. Yleisin rajapinta-aukko: mikä tahansa kirjautunut käyttäjä voi lukea minkä tahansa tietueen vaihtamalla ID:n.
• Asiakkaaseen luottaminen. Hinnat, roolit ja käyttäjä-ID:t pyynnön rungossa voi muokata.
• Koko tietokantarivien palauttaminen. Salasanatiivisteet ja sisäiset kentät vuotavat. Valitse, mitä kukin vastaus sisältää.
• Rajattomat listat. Yksi pyyntö jokaisesta tietueesta voi hidastaa koko sovelluksen.
• 200 OK ja virheviesti sen sisällä. Asiakkaat ja valvonta eivät huomaa epäonnistumista.
• CORS, joka sallii kaiken rajapinnassa, joka käyttää evästeitä.
• Ei terveystarkistusta eikä lokeja, jolloin kuulet katkoksista käyttäjiltä.

Laajempaa julkaisua edeltävää tarkistusta varten katso tietoturvatarkistuslista tekoälyllä rakennetuille sovelluksille.

REST-rajapinnan rakentaminen Mythexissä

Voit pyytää Mythexiltä rajapinnan osana sovellustasi tai omana palvelunaan. Dokumentaation resepti REST API backend sisältää aloituskehotteen: nimeä kehys ja reitit, pyydä selkeät JSON-virheet, säilytä salaisuudet ympäristömuuttujissa ja lisää Dockerfile. Node-, Python-, C#-, Java- ja muut konttipohjaiset taustapalvelut julkaistaan Dockerfilen kautta, ja Mythex hoitaa julkaisun Publish-näkymästä (API-taustapalvelut). Projekti voi ajaa verkkosivua ja API-palvelinta rinnakkain, ja niiden välillä voi vaihtaa esikatselussa. Tallenna avaimet projektin salaisuuksina, ja jos rajapinta tarvitsee tietokannan, pyydä sitä chatissa. Ajastettua työtä API:n ympärille varten katso taustatehtävien ajaminen.

Kysymykset