REST API: co to je, HTTP metody a princip práce v mobilních aplikacích

Co je REST API?

REST API (Representational State Transfer API) — je architektonický styl navržený Royem Fieldingem v jeho doktorské disertaci v roce 2000. Definuje soubor omezení a principů pro navrhování síťových protokolů. API, které splňuje tato omezení, se nazývá RESTful. REST není protokol ani standard — je to architektonický přístup, který využívá existující protokoly (především HTTP) pro výměnu dat mezi klientem a serverem.

Klíčovou myšlenkou REST je architektura orientovaná na zdroje. Místo volání metod na serveru (jako v SOAP nebo RPC) klient pracuje se zdroji: získává jejich seznam, vytváří nové, aktualizuje nebo maže. Každý zdroj je entita domény: uživatel, objednávka, produkt, článek. Zdroj má stav, který je předáván klientovi ve standardizovaném formátu, obvykle JSON. Server neukládá stav klienta mezi požadavky — to je princip stateless, klíčový požadavek REST.

Hlavní charakteristiky REST API:

• Stateless — každý požadavek od klienta obsahuje všechny informace potřebné pro jeho zpracování
• Cacheable — odpovědi serveru musí být výslovně označeny jako ukládatelné nebo neukládatelné do mezipaměti
• Layered system — architektura může zahrnovat prostřední servery, load balancery, proxy
• Uniform interface — jednotné rozhraní pro interakci prostřednictvím HTTP metod, URL a stavových kódů

Principy REST architektury

REST je založen na šesti architektonických omezeních formulovaných Fieldingem. Dodržování těchto omezení zaručuje škálovatelnost, výkon a snadnou integraci. Každý princip řeší konkrétní problém distribuovaných systémů — od potřeby ukládání do mezipaměti až po bezpečnostní požadavky. Podívejme se na každý princip podrobně.

Princip Uniform Interface navíc zahrnuje čtyři dílčí omezení: identifikaci zdrojů prostřednictvím URI, manipulaci se zdroji prostřednictvím reprezentací, sebepopisné zprávy a HATEOAS (hypermédia jako engine stavu aplikace). Poslední dílčí omezení je v praxi často ignorováno — většina moderních REST API neimplementuje HATEOAS plně, což vede k diskusím o tom, zda je takové API „skutečně“ RESTful.

Princip Stateless — jeden z nejdůležitějších pro škálování. Absence relací na serveru znamená, že jakákoli instance serveru může zpracovat jakýkoli požadavek. To zjednodušuje horizontální škálování: stačí přidat nové servery za load balancer. Pro mobilní aplikace stateless také znamená, že požadavek může být odeslán na libovolný CDN server, což je kritické pro globální dostupnost.

HTTP metody v REST

Každá HTTP metoda v REST API odpovídá určité operaci nad zdrojem: GET pro čtení, POST pro vytvoření, PUT pro úplnou aktualizaci, PATCH pro částečnou aktualizaci, DELETE pro smazání. Idempotence metod je klíčovou vlastností: GET, PUT, DELETE jsou idempotentní (opakované provedení dává stejný výsledek), POST a PATCH nikoli. To je důležité pro zpracování síťových chyb, kdy klient neví, zda požadavek dorazil na server.

• GET — získání zdroje nebo seznamu zdrojů. Idempotentní, nemění stav serveru
• POST — vytvoření nového zdroje. Není idempotentní, každé volání vytváří nový zdroj
• PUT — úplná náhrada zdroje. Idempotentní, opakované volání nemění stav po prvním
• PATCH — částečná aktualizace zdroje. Částečně idempotentní (závisí na implementaci)
• DELETE — smazání zdroje. Idempotentní, opakované smazání vrátí 404, nikoli chybu

Stavové kódy HTTP jsou nedílnou součástí REST API. Každý kód má určitý význam: 200 OK pro úspěšný GET, 201 Created pro POST, 204 No Content pro DELETE bez těla odpovědi, 400 Bad Request při neplatných datech, 401 Unauthorized při chybějící autentizaci, 404 Not Found při neexistujícím zdroji. Správné použití stavových kódů činí API samodokumentujícím a zjednodušuje ladění.

Formáty dat: JSON a další

JSON (JavaScript Object Notation) — hlavní formát přenosu dat v REST API. Jeho popularita je dána jednoduchostí, čitelností pro člověka a nativní podporou v JavaScriptu. JSON se přenáší s hlavičkou Content-Type: application/json. Alternativy zahrnují XML (objemný, zastarávající), YAML (pohodlný pro konfiguraci, řidčeji pro API) a Protocol Buffers (binární, efektivní pro systémy s vysokou zátěží).

Struktura JSON objektu v REST API obvykle zahrnuje pole id, type a atributy zdroje. Pro kolekce se používá JSON pole s metadaty stránkování. Moderní REST API se řídí specifikací JSON:API (jsonapi.org) nebo JSON Schema pro validaci odpovědí. Použití jednotného formátu dat zjednodušuje vývoj klientských knihoven a generování dokumentace.

Příklad JSON odpovědi pro seznam uživatelů:

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

Výběr formátu přenosu dat ovlivňuje výkon mobilní aplikace. JSON se komprimuje pomocí GZIP o 70–80%, což jej činí přijatelným pro většinu scénářů. Pro aplikace v reálném čase s velkým objemem dat (streaming, hry) se doporučuje přechod na binární protokoly nebo použití WebSocket v kombinaci s Protocol Buffers.

Příklady REST API požadavků

Podívejme se na praktické příklady práce s REST API na straně mobilní aplikace. Jako příklad vezmeme API pro práci s objednávkami v internetovém obchodě. Pro každou HTTP metodu je ukázán požadavek a očekávaná odpověď serveru. Příklady demonstrují typickou strukturu RESTful API používanou v mobilním vývoji.

GET — získání seznamu objednávek

Požadavek na získání všech objednávek uživatele se stránkováním. Odpověď obsahuje pole objektů objednávek a metainformace pro navigaci po stránkách. Parametry page a per_page se předávají prostřednictvím query string.

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

POST — vytvoření nové objednávky

Vytvoření nové objednávky prostřednictvím POST požadavku. Server vrátí stav 201 Created a vytvořený objekt v těle odpovědi. Důležité: vytváření probíhá na kolekci /api/v1/orders, nikoli na konkrétním zdroji — to je standardní RESTful vzor.

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

// Příklad těla požadavku
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — smazání objednávky

Smazání zdroje se provádí metodou DELETE na konkrétním URL objednávky. Úspěšné smazání vrátí 204 No Content. Idempotence DELETE znamená, že opakovaný požadavek na stejné URL vrátí 404 Not Found, což je správně zpracováno na straně klienta.

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

// Použití ve ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Tyto příklady demonstrují typickou implementaci REST API na straně Androidu s použitím Retrofit a Kotlin Coroutines. Pro iOS aplikace plní obdobnou roli URLSession nebo knihovna Alamofire v kombinaci s protokoly Codable. Struktura REST API zůstává stejná bez ohledu na platformu — mění se pouze způsob provádění požadavků.

Návrh RESTful API: praktická doporučení

Návrh kvalitního RESTful API vyžaduje dodržování konvencí, které činí API intuitivním pro vývojáře. Zdroje by měly být pojmenovány podstatnými jmény v množném čísle (/users, /orders, /products), HTTP metody by měly odrážet operace a URL by měla ukazovat hierarchickou strukturu. Chyby by měly vracet standardizovaný JSON s kódem a zprávou, nikoli pouze HTTP stav. Dodržování těchto konvencí snižuje vstupní bariéru pro nové vývojáře a zjednodušuje integraci.

• Pojmenování zdrojů — množné číslo, kebab-case: /api/v1/user-orders, ne /api/v1/getUserOrders
• Filtrování a řazení — prostřednictvím query parametrů: ?status=active&sort=created_at:desc
• Stránkování — cursor-based pro velké sady, page-based pro malé
• Verzování — prostřednictvím URL (/api/v2/) nebo hlavičky Accept-Version
• Chyby — jednotný formát: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — hlavičky X-RateLimit-Remaining a Retry-After

Jednou z častých chyb při návrhu REST API je nadměrné vnořování zdrojů. Místo /users/1/orders/5/items/3 je lepší použít plochou strukturu s query parametry: /items?order_id=5&user_id=1. To zjednodušuje ukládání do mezipaměti, nevyžaduje podporu dlouhých cest na serveru a je snadněji dokumentovatelné. Plochá architektura je také lépe kompatibilní s graph-based dotazy při přechodu na GraphQL v budoucnu.

Bezpečnost REST API se realizuje prostřednictvím autentizace (JWT, OAuth 2.0) a autorizace na úrovni zdrojů. Každý požadavek by měl ověřit, zda má uživatel přístup k požadovanému zdroji. HTTPS je povinné — bez šifrování jsou tokeny a data přenášena v otevřeném textu. Pro mobilní aplikace se doporučuje použití OAuth 2.0 s PKCE (Proof Key for Code Exchange) pro bezpečné získávání tokenů.

Verzování a ukládání do mezipaměti

Verzování REST API je nezbytné pro zpětnou kompatibilitu při změnách. Nejčastější přístupy: verze v URL (/api/v1/orders), verze v hlavičce (Accept: application/vnd.myapi.v1+json) a verze v query parametru (?api_version=1). URL verzování je nejpopulárnější metodou, protože je jasně viditelné v logech a dokumentaci. Porušuje však princip REST o jedinečném URL zdroje.

Ukládání do mezipaměti v REST API se realizuje prostřednictvím HTTP hlaviček Cache-Control, ETag a Last-Modified. GET požadavky označené jako ukládatelné mohou být obslouženy z mezipaměti prohlížeče nebo proxy bez kontaktování serveru. Pro mobilní aplikace je ukládání do mezipaměti obzvláště důležité — snižuje spotřebu dat a zrychluje zobrazení dříve načtených dat při špatném připojení. ETag je hash obsahu odpovědi: klient jej odešle v If-None-Match a server vrátí 304 Not Modified, pokud se data nezměnila.

Moderní alternativy REST API zahrnují GraphQL (flexibilní výběr dat klientem) a gRPC (binární protokol na HTTP/2 pro mikroslužby). REST však zůstává hlavním standardem pro veřejná API díky své jednoduchosti, univerzálnosti a široké podpoře nástrojů. Volba mezi REST a alternativami závisí na konkrétních požadavcích projektu: složitosti dotazů, objemu dat, požadavcích na aktualizace v reálném čase.