REST API: ce este, metode HTTP și principiul de funcționare în aplicațiile mobile

Ce este REST API?

REST API (Representational State Transfer API) — este un stil arhitectural propus de Roy Fielding în teza sa de doctorat în anul 2000. Acesta definește un set de constrângeri și principii pentru proiectarea protocoalelor de rețean. Un API care respectă aceste constrângeri se numește RESTful. REST nu este un protocol sau un standard — este o abordare arhitecturală care folosește protocoale existente (preponderent HTTP) pentru schimbul de date între client și server.

Ideea cheie a REST este arhitectura orientată pe resurse. În loc să apeleze metode pe server (ca în SOAP sau RPC), clientul operează cu resurse: obține lista acestora, creează altele noi, le actualizează sau le șterge. Fiecare resursă este o entitate din domeniu: utilizator, comandă, produs, articol. Resursa are o stare care este transmisă clientului într-un format standardizat, de obicei JSON. Serverul nu stochează starea clientului între cereri — acesta este principiul stateless, o cerință cheie a REST.

Principalele caracteristici ale REST API:

• Stateless — fiecare cerere de la client conține toate informațiile necesare pentru procesarea sa
• Cacheable — răspunsurile serverului trebuie să fie marcate explicit ca stocabile în cache sau nu
• Layered system — arhitectura poate include servere intermediare, balansoare de sarcină, proxy-uri
• Uniform interface — interfață uniformă de interacțiune prin metode HTTP, URL-uri și coduri de stare

Principiile arhitecturii REST

REST se bazează pe șase constrângeri arhitecturale formulate de Fielding. Respectarea acestor constrângeri garantează scalabilitate, performanță și ușurință de integrare. Fiecare principiu rezolvă o problemă specifică a sistemelor distribuite — de la necesitatea stocării în cache până la cerințele de securitate. Să examinăm fiecare principiu în detaliu.

Principiul Uniform Interface include în plus patru sub-constrângeri: identificarea resurselor prin URI, manipularea resurselor prin reprezentări, mesaje auto-descriptive și HATEOAS (hipermedia ca motor al stării aplicației). Ultima sub-constrângere este adesea ignorată în practică — majoritatea API-urilor REST moderne nu implementează pe deplin HATEOAS, ceea ce duce la discuții despre dacă un astfel de API este „adevărat” RESTful.

Principiul Stateless — unul dintre cele mai importante pentru scalare. Absența sesiunilor pe server înseamnă că orice instanță a serverului poate procesa orice cerere. Aceasta simplifică scalarea orizontală: este suficient să adăugați noi servere în spatele balansorului de sarcină. Pentru aplicațiile mobile, stateless înseamnă, de asemenea, că cererea poate fi trimisă la orice server CDN, ceea ce este critic pentru disponibilitatea globală.

Metodele HTTP în REST

Fiecare metodă HTTP în REST API corespunde unei operații specifice asupra resursei: GET pentru citire, POST pentru creare, PUT pentru actualizare completă, PATCH pentru actualizare parțială, DELETE pentru ștergere. Idempotența metodelor este o caracteristică cheie: GET, PUT, DELETE sunt idempotente (executarea repetată dă același rezultat), POST și PATCH — nu. Aceasta este importantă pentru gestionarea erorilor de rețean, când clientul nu știe dacă cererea a ajuns la server.

• GET — obținerea unei resurse sau a unei liste de resurse. Idempotent, nu modifică starea serverului
• POST — crearea unei resurse noi. Neidempotent, fiecare apel creează o resursă nouă
• PUT — înlocuirea completă a resursei. Idempotent, apelul repetat nu modifică starea după primul
• PATCH — actualizarea parțială a resursei. Parțial idempotent (depinde de implementare)
• DELETE — ștergerea resursei. Idempotent, ștergerea repetată returnează 404, nu o eroare

Codurile de stare HTTP sunt o parte integrantă a REST API. Fiecare cod are un sens specific: 200 OK pentru GET reușit, 201 Created pentru POST, 204 No Content pentru DELETE fără corp de răspuns, 400 Bad Request pentru date invalide, 401 Unauthorized pentru lipsa autentificării, 404 Not Found pentru resursa lipsă. Utilizarea corectă a codurilor de stare face API-ul auto-documentabil și simplifică depanarea.

Formatele de date: JSON și altele

JSON (JavaScript Object Notation) — formatul principal de transmitere a datelor în REST API. Popularitatea sa se explică prin simplitate, lizibilitate umană și suport nativ în JavaScript. JSON este transmis cu antetul Content-Type: application/json. Alternativele includ XML (voluminos, în declin), YAML (confortabil pentru configurare, mai rar pentru API) și Protocol Buffers (binar, eficient pentru sisteme cu încărcare mare).

Structura obiectului JSON în REST API include de obicei câmpurile id, type și atributele resursei. Pentru colecții se utilizează un tablou JSON cu metadate de paginare. API-urile REST moderne respectă specificația JSON:API (jsonapi.org) sau JSON Schema pentru validarea răspunsurilor. Utilizarea unui format uniform de date simplifică dezvoltarea bibliotecilor client și generarea documentației.

Exemplu de răspuns JSON pentru o listă de utilizatori:

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

Alegerea formatului de transmitere a datelor influențează performanța aplicației mobile. JSON se comprimă prin GZIP cu 70–80%, ceea ce îl face acceptabil pentru majoritatea scenariilor. Pentru aplicații în timp real cu volum mare de date (streaming, jocuri), se recomandă trecerea la protocoale binare sau utilizarea WebSocket în combinație cu Protocol Buffers.

Exemple de cereri REST API

Să examinăm exemple practice de lucru cu REST API din partea aplicației mobile. Ca exemplu, vom lua un API pentru lucrul cu comenzi într-un magazin online. Pentru fiecare metodă HTTP sunt prezentate cererea și răspunsul așteptat al serverului. Exemplele demonstrează structura tipică a unui RESTful API utilizat în dezvoltarea mobilă.

GET — obținerea listei de comenzi

Cerere pentru obținerea tuturor comenzilor utilizatorului cu paginare. Răspunsul conține un tablou de obiecte comandă și meta-informații pentru navigarea paginată. Parametrii page și per_page sunt transmiși prin query string.

// Interfața Retrofit pentru 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 — crearea unei comenzi noi

Crearea unei comenzi noi printr-o cerere POST. Serverul returnează statusul 201 Created și obiectul creat în corpul răspunsului. Important: crearea se face pe colecția /api/v1/orders, nu pe o resursă concretă — acesta este un model standard RESTful.

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

// Exemplu de corp de cerere
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — ștergerea unei comenzi

Ștergerea resursei se execută prin metoda DELETE la URL-ul concret al comenzii. Ștergerea reușită returnează 204 No Content. Idempotența DELETE înseamnă că o cerere repetată la același URL va returna 404 Not Found, ceea ce este gestionat corect de client.

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

// Utilizare în ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Aceste exemple demonstrează implementarea tipică a REST API pe partea de Android utilizând Retrofit și Kotlin Coroutines. Pentru aplicațiile iOS, un rol similar îl joacă URLSession sau biblioteca Alamofire în combinație cu protocoalele Codable. Structura REST API rămâne aceeași indiferent de platformă — se schimbă doar modul de executare a cererilor.

Proiectarea RESTful API: recomandări practice

Proiectarea unui RESTful API de calitate necesită respectarea convențiilor care fac API-ul intuitiv pentru programatori. Resursele ar trebui denumite cu substantive la plural (/users, /orders, /products), metodele HTTP să reflecte operațiile, iar URL-urile — ierarhia de încuibare. Erorile ar trebui să returneze un JSON standardizat cu cod și mesaj, nu doar un status HTTP. Respectarea acestor convenții reduce pragul de intrare pentru noii dezvoltatori și simplifică integrarea.

• Denumirea resurselor — plural, kebab-case: /api/v1/user-orders, nu /api/v1/getUserOrders
• Filtrarea și sortarea — prin parametri query: ?status=active&sort=created_at:desc
• Paginarea — cursor-based pentru seturi mari, page-based pentru seturi mici
• Versionarea — prin URL (/api/v2/) sau antetul Accept-Version
• Erorile — format uniform: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — antetele X-RateLimit-Remaining și Retry-After

Una dintre greșelile frecvente la proiectarea REST API este încuibarea excesivă a resurselor. În loc de /users/1/orders/5/items/3, este mai bine să folosiți o structură plată cu parametri query: /items?order_id=5&user_id=1. Aceasta simplifică stocarea în cache, nu necesită suport pentru și lungi pe server și este mai ușor de documentat. Arhitectura plată este, de asemenea, mai compatibilă cu cererile graph-based la trecerea la GraphQL în viitor.

Securitatea REST API se realizează prin autentificare (JWT, OAuth 2.0) și autorizare la nivel de resurse. Fiecare cerere trebuie să verifice dacă utilizatorul are acces la resursa solicitată. HTTPS este obligatoriu — fără criptare, token-urile și datele sunt transmise în clar. Pentru aplicațiile mobile, se recomandă utilizarea OAuth 2.0 cu PKCE (Proof Key for Code Exchange) pentru obținerea sigură a token-urilor.

Versionarea și stocarea în cache

Versionarea REST API este necesară pentru compatibilitatea inversă la modificări. Cele mai frecvente abordări: versiunea în URL (/api/v1/orders), versiunea în antet (Accept: application/vnd.myapi.v1+json) și versiunea în parametrul query (?api_version=1). Versionarea prin URL este cea mai populară metodă, deoarece este vizibilă clar în loguri și documentație. Însă aceasta încalcă principiul REST despre URL-ul unic al resursei.

Stocarea în cache în REST API se realizează prin antetele HTTP Cache-Control, ETag și Last-Modified. Cererile GET marcate ca stocabile în cache pot fi servite din memoria cache a browserului sau a proxy-ului fără a apela serverul. Pentru aplicațiile mobile, stocarea în cache este deosebit de importantă — reduce consumul de trafic și accelerează afișarea datelor încărcate anterior la o conexiune slabă. ETag este un hash al conținutului răspunsului: clientul îl trimite în If-None-Match, iar serverul returnează 304 Not Modified dacă datele nu s-au schimbat.

Alternativele moderne la REST API includ GraphQL (selectarea flexibilă a datelor de către client) și gRPC (protocol binar pe HTTP/2 pentru microservicii). Totuși, REST rămâne standardul principal pentru API-urile publice datorită simplității, universalității și suportului extins de instrumente. Alegerea între REST și alternative depinde de cerințele specifice ale proiectului: complexitatea cererilor, volumul datelor, cerințele de actualizare în timp real.