Hogyan építsünk REST API-t: tervezés, biztonság és telepítés

REST API építéséhez sorold fel azokat az erőforrásokat, amelyeket az alkalmazásod kezel (felhasználók, rendelések, foglalások), adj mindegyiknek URL-t, például /orders és /orders/{id}, a műveletekhez pedig HTTP-metódusokat használj: GET olvasáshoz, POST létrehozáshoz, PATCH módosításhoz, DELETE törléshez. Adj vissza JSON-t értelmes státuszkódokkal, validálj minden bemenetet, a szerveren követelj meg hitelesítést és rekordonkénti jogosultság-ellenőrzést, a listákat pedig lapozd. Ezután dokumentáld a végpontokat, és telepítsd az API-t HTTPS mögé.

Ez az útmutató a tervezési döntéseket, egy kidolgozott útvonalkészletet, AI-alapú építőeszközökhöz írt promptokat és a biztonsági lyukakat okozó hibákat tárgyalja. Ha az API-k még újdonságot jelentenek, kezdd az API-val kapcsolatos alapokkal.

Mikor van szükséged REST API-ra

• A webes frontendnek adatokat kell mentenie és betöltenie egy szerverről
• Egy mobilalkalmazásnak, partnernek vagy automatizálási eszköznek hozzá kell férnie az adataidhoz
• Más szolgáltatások eseményeket küldenek neked (webhookok)
• A munkát frontend- és backend-csapat között osztod meg

A REST a legelterjedtebb stílus, de nem az egyetlen. A REST vs GraphQL összehasonlítás azt magyarázza el, mikor jobb egyetlen, rugalmas lekérdező végpont.

Először a tervezés: erőforrások és útvonalak

Írd le az alkalmazásodban szereplő főneveket, és azt, hogy mit csinálnak velük az emberek. Egy egyszerű foglalási alkalmazásnál:

Ezek a létrehozás, olvasás, módosítás és törlés műveleteire képeződnek le; lásd mi a CRUD. Érdemes követni ezeket a konvenciókat:

• Többes számú főnevek, igék nélkül az URL-ekben: /bookings, nem /getBookings.
• Csak egy szintet ágyazz, ha ez egyértelművé teszi a tulajdonjogot: /bookings/{id}/notes.
• A nem CRUD jellegű műveletek lehetnek almeroforrások: a POST /bookings/{id}/cancel világosabb, mint egy titokzatos PATCH.
• Következetes elnevezés a mezőknél, például created_at mindenütt.

Állapotkódok és hibák

Használj szabványos HTTP-kódokat, hogy a kliensek szövegelemzés nélkül értsék, mi történt:

Az összes hibát egységes JSON-formátumban add vissza, például {"error": {"code": "slot_taken", "message": "Ez az időpont már nem elérhető."}}, és soha ne tegyél hibaválaszba hívási veremkimenetet (stack trace), adatbázishibát vagy belső részletet.

Lehetőségek és kompromisszumok

Lépésről lépésre

1. Sorold fel az erőforrásokat és útvonalakat a fentiek szerint, beleértve azt is, ki hívhatja őket.
2. Modellezd az adatokat az adatbázisban a szükséges mezőkkel és kapcsolatokkal.
3. Először az olvasó útvonalakat építsd meg, utána a létrehozást, módosítást és törlést.
4. Validálj minden írási műveletnél egy sémakönyvtárral: kötelező mezők, típusok, hosszok, engedélyezett értékek. Az ismeretlen mezőket utasítsd el.
5. Adj hozzá hitelesítést, majd rekordonkénti jogosultság-ellenőrzést: a /bookings/42 lekérésénél azt kell ellenőrizni, hogy a 42-es foglalás a hívóé-e, nem csak azt, hogy valaki be van-e jelentkezve.
6. Lapozz minden listát, és korlátozd az oldalméretet.
7. Korlátozd a kérésszámot a bejelentkezésnél és a költséges útvonalaknál. Lásd kérésszám-korlátozás.
8. Állíts be CORS-t csak akkor, ha más domainen futó böngészőknek is hívniuk kell az API-t, és ezeket a forrásokat kifejezetten sorold fel. A CORS-hibák javítása elmagyarázza, milyen hibákkal találkozhatsz.
9. Írj dokumentációt és teszteket minden útvonalhoz, a hibás eseteket is beleértve.
10. Telepítsd úgy, hogy a titkos adatok környezeti változókban legyenek, HTTPS-sel, naplózással és állapotellenőrzéssel.

Promptok az AI-építőeszköznek

Vázlat:

Készíts REST API-t foglalásokhoz ezekkel az útvonalakkal: GET /api/health, GET /api/bookings (lapozva, oldalanként legfeljebb 50), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Az adatokat a mi adatbázisunkban tárold. A kéréstörzseket sémakönyvtárral validáld, és utasítsd el az ismeretlen mezőket. A JSON-hibákat {"error": {"code", "message"}} alakban add vissza, megfelelő állapotkódokkal (400, 401, 403, 404, 409). A titkos adatokat környezeti változókban tartsd.

Biztonság:

Minden foglalási útvonalhoz kérj bejelentkezést. Minden olvasás, módosítás és törlés esetén ellenőrizd a szerveren, hogy a foglalás az aktuális felhasználóé-e; ha nem, 404-et adj vissza. Soha ne fogadj el felhasználói azonosítót vagy szerepkört a kéréstörzsből. A POST /api/bookings útvonalat korlátozd felhasználónként percenként 20 kérésre. A hibákat a szerveren naplózd, de ne add vissza a hívási vermet.

Dokumentáció:

Írj OpenAPI-leírást ezekhez az útvonalakhoz, és egy rövid README-t minden útvonalhoz példakérésekkel és példaválaszokkal.

Az API tesztelése

Teszteld a frontenden kívülről, mert a támadók is ezt fogják tenni:

• Minden útvonal érvényes bemenettel működik, és a dokumentált alakot és kódot adja vissza
• A hiányzó vagy érvénytelen mezők világos üzenettel 400-at adnak
• Token nélkül minden védett útvonal 401-et ad
• Ha az A felhasználó a B felhasználó rekordját kéri ID alapján, 404-et vagy 403-at kap
• A listák lapozottak; egy hatalmas limit értéket levágunk
• Az ütköző létrehozások 409-et adnak, nem 500-at
• A kérésszám-korlátok 429-et adnak
• A hibaválaszok nem tartalmaznak hívási vermet, SQL-t vagy titkos adatot
• A CORS csak a kívánt forrásokat engedi

Gyakori hibák

• Bejelentkezés ellenőrzése, de tulajdonjog nem. A legelterjedtebb API-hiba: bármelyik bejelentkezett felhasználó bármely rekordot elérhet, haz átírja az azonosítót.
• A kliensben bízás. Az árak, szerepkörök és felhasználói azonosítók a kéréstörzsben átírhatók.
• Teljes adatbázissorok visszaadása. Jelszó-hash és belső mezők szivárognak ki. Válaszd ki, mit tartalmaz minden válasz.
• Korlátlan listák. Egy kérés az összes rekordért lelassíthatja az egész alkalmazást.
• 200 OK hibaüzenettel a törzsben. A kliensek és a figyelőrendszerek nem látják, hogy hiba történt.
• Mindenkinek engedélyező CORS olyan API-n, amely sütiket használ.
• Nincs állapotellenőrzés vagy napló, így a felhasználóktól tudod meg, hogy leállás volt.

A launch előtti átfogóbb átnézéshez lásd az AI-val épített alkalmazások biztonsági ellenőrzőlistáját.

REST API építése a Mythexben

Az API-t kérheted a Mythextől az alkalmazásod részeként vagy önálló szolgáltatásként is. A REST API backend dokumentációs recept kezdő promptot ad: nevezd meg a keretrendszert és az útvonalakat, kérj egyértelmű JSON-hibákat, a titkos adatokat környezeti változókban tartsd, és adj Dockerfile-t. A Node, Python, C#, Java és más nyelvű konténeres backendek Dockerfile-on keresztül publikálhatók, a telepítést pedig a Mythex kezeli a Publish menüből (API backendek). Egy projekt futtathat weboldalt és API-szervert egymás mellett, a kettő között pedig az előnézetben válthatsz. A titkos adatokat projekt-titokként tárold, és ha az API adatbázist igényel, kérd azt a csevegésben. Az API körüli ütemezett feladatokhoz lásd hogyan futtassunk háttérfeladatokat.

Kérdések