REST API Tervezési Alapelvek: Hogyan építsünk tiszta végpontokat?

A modern webes és mobilalkalmazások (mint például egy iOS vagy Android app), valamint az IoT (Internet of Things) eszközök és a szerverek közötti kommunikáció legelterjedtebb formája a REST (Representational State Transfer) architektúra. A REST API-k határozzák meg azokat a szabványokat és "végpontokat" (endpoints), amelyeken keresztül két rendszer hálózaton keresztül JSON vagy XML adatokat cserélhet.

Egy API akkor jó, ha a fejlesztők (akik használni fogják) azonnal megértik a működését pusztán a végpontok elolvasásából. A tiszta, kiszámítható és skálázható REST API tervezéséhez elengedhetetlen néhány alapvető szabály szigorú betartása.

1. Erőforrás-alapú URL struktúra (Nouns, nem Verbs)

A leggyakoribb hiba a kezdő fejlesztőknél, hogy a végpontok nevébe beleírják a cselekvést (pl. /getUsers vagy /updateProfile). A REST alapelve szerint az URL-eknek mindig főneveket (erőforrásokat) kell jelölniük, a cselekvést pedig maga a HTTP metódus határozza meg. A többes szám használata (pl. /users a /user helyett) a legtöbb iparági szabvány szerint preferált.

Rossz megközelítés (Ige)	Helyes megközelítés (Főnév + HTTP metódus)
`POST /getUsers`	`GET /users`
`POST /createNewUser`	`POST /users`
`GET /deleteUser?id=5`	`DELETE /users/5`

2. A HTTP metódusok szemantikája

Ahogy az előző pontból is látszik, az URL csak a célpontot mutatja. Hogy mi történik a célponttal, azt a HTTP igék (methods) döntik el:

GET: Erőforrások lekérése. Ez egy biztonságos és idempotens művelet (nem módosíthat adatot a szerveren).
POST: Új erőforrás létrehozása a szerveren (pl. új regisztráció).
PUT: Egy létező erőforrás teljes, komplett felülírása/frissítése.
PATCH: Egy létező erőforrás részleges frissítése (pl. csak a jelszó megváltoztatása).
DELETE: Erőforrás törlése a szerverről.

3. Megfelelő HTTP státuszkódok használata

Egy jó REST API beszédes. Nem elég, ha a JSON válaszban egy {"status": "error"} üzenetet küldünk úgy, hogy közben a szerver 200-as (OK) HTTP státuszkóddal válaszol. A szervernek a hálózati szinten kell közölnie az eredményt:

200 OK: Sikeres GET, PUT vagy DELETE művelet.
201 Created: Sikeres POST művelet (létrejött az új rekord).
400 Bad Request: Kliens hiba (pl. hiányzó mezők a validáció során).
401 Unauthorized: Nincs vagy érvénytelen az API kulcs / JWT token.
403 Forbidden: Hitelesített a felhasználó, de nincs jogosultsága (pl. admin felülethez).
404 Not Found: A keresett erőforrás (pl. /users/999) nem létezik.
500 Internal Server Error: A szerver belső hibája (pl. adatbázis kapcsolat megszakadt).

4. Verziókövetés (Versioning)

Ahogy az API fejlődik, elkerülhetetlenek a "törő változtatások" (breaking changes). Hogy a meglévő kliensek (pl. régi mobil appok) ne omoljanak össze, mindig verziózzuk az API-t. A legelterjedtebb módszer az URL-be épített verzió, például: /api/v1/users és /api/v2/users.

Összegzés

A REST API tervezés nem egy szigorú törvénykönyv, de a fenti konvenciók betartásával olyan rendszert építhetsz, amelyhez más fejlesztők örömmel és könnyen tudnak csatlakozni. A kiszámíthatóság és a szabványok követése kulcsfontosságú a modern mikroszolgáltatás-alapú rendszerekben.

Gyakran Ismételt Kérdések (GYIK)

Mi a különbség a PUT és a PATCH között?

A PUT művelet elméletben a teljes objektumot cseréli (ha valami hiányzik a kérésből, az a mező nullázódik). A PATCH ezzel szemben csak a megadott mezőket frissíti (pl. csak az e-mail címet), a többi adat érintetlen marad.

Hogyan kezeljem a listák lapozását (Pagination)?

Ha egy végpont több ezer rekordot adna vissza, kötelező a lapozás. Ezt leggyakrabban URL paraméterekkel (Query Parameters) oldjuk meg: GET /articles?page=2&limit=20.