REST API: mi ez, HTTP metódusok és működési elv a mobilalkalmazásokban

Mi az a REST API?

REST API (Representational State Transfer API) — egy architektúrai stílus, amelyet Roy Fielding javasolt doktori értekezésében 2000-ben. Meghatározza a hálózati protokollok tervezésének korlátait és elveit. Az e korlátoknak megfelelő API-t RESTful-nak nevezik. A REST nem protokoll vagy szabvány — egy architektúrai megközelítés, amely meglévő protokollokat (főleg HTTP-t) használ az adatok cseréjére a kliens és a szerver között.

A REST kulcsötlete az erőforrás-orientált architektúra. Ahelyett, hogy metódusokat hívna a szerveren (mint a SOAP-ban vagy RPC-ben), a kliens erőforrásokkal dolgozik: lekéri a listájukat, újakat hoz létre, frissít vagy töröl. Minden erőforrás a tartomány egy entitása: felhasználó, rendelés, termék, cikk. Az erőforrásnak állapota van, amelyet szabványos formátumban, általában JSON-ban továbbítanak a kliensnek. A szerver nem tárolja a kliens állapotát a kérések között — ez a stateless elv, a REST egyik fő követelménye.

A REST API fő jellemzői:

• Stateless — minden kliens kérés tartalmazza a feldolgozáshoz szükséges összes információt
• Cacheable — a szerver válaszait egyértelműen gyorsítótárazható vagy nem gyorsítótárazható ként kell megjelölni
• Layered system — az architektúra tartalmazhat közbenső szervereket, terheléselosztókat, proxy-kat
• Uniform interface — egységes interakciós interfész HTTP metódusokon, URL-eken és állapotkódokon keresztül

A REST architektúra elvei

REST hat, Fielding által megfogalmazott architektúrai korlátozáson alapul. E korlátozások betartása garantálja a skálázhatóságot, a teljesítményt és az egyszerű integrációt. Minden elv egy adott elosztott rendszer problémáját oldja meg — a gyorsítótár szükségességétől a biztonsági követelményekig. Vizsgáljuk meg részletesen minden elvet.

Az Uniform Interface elv további négy al-korlátozást foglal magában: erőforrások azonosítása URI-n keresztül, erőforrások manipulálása reprezentációkon keresztül, önleíró üzenetek és HATEOAS (hipermédia, mint az alkalmazás állapotának motorja). Az utolsó al-korlátozást a gyakorlatban gyakran figyelmen kívül hagyják — a legtöbb modern REST API nem implementálja teljes mértékben a HATEOAS-t, ami vitákhoz vezet arról, hogy egy ilyen API „igazi” RESTful-e.

A Stateless elv — az egyik legfontosabb a skálázáshoz. A munkamenetek hiánya a szerveren azt jelenti, hogy a szerver bármely példánya bármely kérést feldolgozhatja. Ez leegyszerűsíti a horizontális skálázást: elegendő új szervereket hozzáadni a terheléselosztó mögé. Mobilalkalmazások számára a stateless azt is jelenti, hogy a kérés bármely CDN szerverre elküldhető, ami kritikus a globális elérhetőség szempontjából.

HTTP metódusok a REST-ben

Minden HTTP metódus a REST API-ban egy adott műveletnek felel meg az erőforráson: GET olvasáshoz, POST létrehozzáshoz, PUT teljes frissítéshez, PATCH részleges frissítéshez, DELETE törléshez. A metódusok idempotenciája kulcsjellemző: a GET, PUT, DELETE idempotens (ismételt végrehajtás ugyanazt az eredményt adja), a POST és PATCH nem. Ez fontos a hálózati hibák kezelésénél, amikor a kliens nem tudja, hogy a kérés elérte-e a szervert.

• GET — erőforrás vagy erőforráslista lekérése. Idempotens, nem változtatja meg a szerver állapotát
• POST — új erőforrás létrehozása. Nem idempotens, minden hívás új erőforrást hoz létre
• PUT — erőforrás teljes cseréje. Idempotens, ismételt hívás nem változtatja meg az állapotot
• PATCH — erőforrás részleges frissítése. Részben idempotens (implementációfüggő)
• DELETE — erőforrás törlése. Idempotens, ismételt törlés 404-et ad, nem hibát

A HTTP állapotkódok a REST API szerves részét képezik. Minden kódnak meghatározott jelentése van: 200 OK sikeres GET-hez, 201 Created POST-hoz, 204 No Content válasz törzs nélküli DELETE-hez, 400 Bad Request érvénytelen adatokhoz, 401 Unauthorized hitelesítés hiányában, 404 Not Found erőforrás hiányában. Az állapotkódok helyes használata öndokumentálóvá teszi az API-t és egyszerűsíti a hibakeresést.

Adatformátumok: JSON és mások

JSON (JavaScript Object Notation) — a fő adattovábbítási formátum a REST API-ban. Népszerűségét az egyszerűség, az ember általi olvashatóság és a JavaScript natív támogatása magyarázza. A JSON a Content-Type: application/json fejléccel kerül továbbításra. Alternatívák közé tartozik az XML (terjedelmes, elavuló), a YAML (konfigurációhoz kényelmes, API-hoz ritka) és a Protocol Buffers (bináris, hatékony nagy terhelésű rendszerekhez).

A JSON objektum szerkezete a REST API-ban általában tartalmazza az id, type mezőket és az erőforrás attribútumait. Gyűjtemények esetén JSON tömb kerül használatra lapozási metaadatokkal. A modern REST API-k követik a JSON:API specifikációt (jsonapi.org) vagy a JSON Schema-t a válaszok érvényesítéséhez. Az egységes adatformátum használata leegyszerűsíti a klienskönyvtárak fejlesztését és a dokumentáció generálását.

Példa JSON válaszra egy felhasználói listához:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Az adattovábbítási formátum választása befolyásolja a mobilalkalmazás teljesítményét. A JSON GZIP segítségével 70–80%-kal tömöríthető, ami elfogadhatóvá teszi a legtöbb forgatókönyv számára. Valós idejű, nagy adatmennyiséggel dolgozó alkalmazásokhoz (streaming, játékok) bináris protokollokra váltás vagy WebSocket használata javasolt Protocol Buffers-szel kombinálva.

Példák REST API kérésekre

Tekintsük át a REST API-val való munka gyakorlati példáit a mobilalkalmazás oldalán. Példaként vegyünk egy API-t a rendelések kezeléséhez egy online áruházban. Minden HTTP metódushoz megjelenítjük a kérést és a várt szerver választ. A példák bemutatják a mobilfejlesztésben használt tipikus RESTful API szerkezetét.

GET — rendelések listájának lekérése

Kérés a felhasználó összes rendelésének lekérésére lapozással. A válasz rendelés objektumok tömbjét és meta-információkat tartalmaz az oldalnavigációhoz. A page és per_page paraméterek a query stringen keresztül kerülnek továbbításra.

// Retrofit interfész REST API-hoz
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — új rendelés létrehozása

Új rendelés létrehozása POST kéréssel. A szerver 201 Created állapotot és a létrehozott objektumot adja vissza a válasz törzsében. Fontos: a létrehozás a /api/v1/orders gyűjteményen történik, nem egy konkrét erőforráson — ez egy szabványos RESTful minta.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Kérés törzsének példája
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — rendelés törlése

Az erőforrás törlése a DELETE metódussal történik a rendelés konkrét URL-jén. A sikeres törlés 204 No Content választ ad. A DELETE idempotenciája azt jelenti, hogy az ismételt kérés ugyanarra az URL-re 404 Not Found-ot ad, amit a kliens oldala helyesen kezel.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Használat a ViewModel-ben
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Ezek a példák bemutatják a REST API tipikus implementációját Android oldalon Retrofit és Kotlin Coroutines használatával. iOS alkalmazások esetén az URLSession vagy az Alamofire könyvtár tölt be hasonló szerepet a Codable protokollokkal kombinálva. A REST API szerkezete platformtól függetlenül ugyanaz marad — csak a kérések végrehajtásának módja változik.

RESTful API tervezés: gyakorlati javaslatok

Minőségi RESTful API tervezése megköveteli azon konvenciók betartását, amelyek intuitívvá teszik az API-t a fejlesztők számára. Az erőforrásokat többes számú főnevekkel kell elnevezni (/users, /orders, /products), a HTTP metódusoknak tükrözniük kell a műveleteket, az URL-eknek pedig a hierarchikus szerkezetet. A hibáknak szabványos JSON-t kell visszaadniuk kóddal és üzenettel, nem csak HTTP állapotot. E konvenciók betartása csökkenti a belépési küszöböt az új fejlesztők számára és egyszerűsíti az integrációt.

• Erőforrások elnevezése — többes szám, kebab-case: /api/v1/user-orders, nem /api/v1/getUserOrders
• Szűrés és rendezés — query paramétereken keresztül: ?status=active&sort=created_at:desc
• Lapozás — cursor-based nagy halmazokhoz, page-based kicsikhez
• Verziókezelés — URL-en (/api/v2/) vagy Accept-Version fejlécen keresztül
• Hibák — egységes formátum: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — X-RateLimit-Remaining és Retry-After fejlécek

Az egyik gyakori hiba a REST API tervezésében az erőforrások túlzott egymásba ágyazása. A /users/1/orders/5/items/3 helyett jobb sík szerkezetet használni query paraméterekkel: /items?order_id=5&user_id=1. Ez leegyszerűsíti a gyorsítótárazást, nem igényel hosszú útvonalak támogatását a szerveren és könnyebben dokumentálható. A sík architektúra jobban kompatibilis a graph-alapú lekérdezésekkel a jövőbeli GraphQL-re váltáskor.

A REST API biztonsága hitelesítésen (JWT, OAuth 2.0) és autorizáción keresztül valósul meg erőforrás szinten. Minden kérésnek ellenőriznie kell, hogy a felhasználónak van-e hozzáférése a kért erőforráshoz. A HTTPS kötelező — titkosítás nélkül a tokenek és adatok sík szövegként kerülnek továbbításra. Mobilalkalmazások számára az OAuth 2.0 PKCE-vel (Proof Key for Code Exchange) történő használata javasolt a tokenek biztonságos megszerzéséhez.

Verziókezelés és gyorsítótár

A REST API verziókezelése szükséges a visszafelé kompatibilitás biztosításához változtatások esetén. A leggyakoribb megközelítések: verzió az URL-ben (/api/v1/orders), verzió a fejlécben (Accept: application/vnd.myapi.v1+json) és verzió a query paraméterben (?api_version=1). Az URL verziókezelés a legnépszerűbb módszer, mivel jól látható a naplókban és dokumentációban. Azonban megsérti a REST azon elvét, hogy egy erőforrásnak egy URL-je legyen.

A gyorsítótárazás a REST API-ban HTTP fejléceken keresztül valósul meg: Cache-Control, ETag és Last-Modified. A gyorsítótárazhatóként jelölt GET kérések kiszolgálhatók a böngésző vagy proxy gyorsítótárából a szerver megkeresése nélkül. Mobilalkalmazások számára a gyorsítótárazás különösen fontos — csökkenti az adatforgalmat és gyorsítja a korábban betöltött adatok megjelenítését gyenge kapcsolat esetén. Az ETag a válasz tartalmának hash-je: a kliens elküldi az If-None-Match-ben, a szerver pedig 304 Not Modified-et ad vissza, ha az adatok nem változtak.

A REST API modern alternatívái közé tartozik a GraphQL (rugalmas adatválasztás a kliens által) és a gRPC (bináris protokoll HTTP/2-n mikroservices számára). A REST azonban továbbra is a fő szabvány marad a nyilvános API-k számára egyszerűsége, általánossága és széles körű eszköztámogatása miatt. A REST és alternatívái közötti választás a projekt konkrét követelményeitől függ: a kérések összetettségétől, az adatok mennyiségétől, a valós idejű frissítési igényektől.