REST API: wat is het, HTTP-methoden en werkingsprincipe in mobiele apps

Wat is REST API?

REST API (Representational State Transfer API) — is een architectuurstijl voorgesteld door Roy Fielding in zijn proefschrift in 2000. Het definieert een set beperkingen en principes voor het ontwerpen van netwerkprotocollen. Een API die aan deze beperkingen voldoet, wordt RESTful genoemd. REST is geen protocol of standaard — het is een architectuurbenadering die bestaande protocollen (voornamelijk HTTP) gebruikt voor gegevensuitwisseling tussen client en server.

Het kernidee van REST is resource-georiënteerde architectuur. In plaats van methoden op de server aan te roepen (zoals in SOAP of RPC), werkt de client met resources: hij verkrijgt hun lijst, maakt nieuwe aan, werkt bij of verwijdert. Elke resource is een entiteit uit het domein: gebruiker, bestelling, product, artikel. Een resource heeft een status die in een gestandaardiseerd formaat, meestal JSON, aan de client wordt doorgegeven. De server slaat de status van de client niet op tussen verzoeken — dit is het stateless-principe, een kernvereiste van REST.

Belangrijkste kenmerken van REST API:

• Stateless — elk verzoek van de client bevat alle benodigde informatie voor verwerking
• Cacheable — serverantwoorden moeten expliciet worden gemarkeerd als cachebaar of niet-cachebaar
• Layered system — de architectuur kan tussenliggende servers, load balancers, proxies bevatten
• Uniform interface — uniforme interactie-interface via HTTP-methoden, URL's en statuscodes

Principes van REST-architectuur

REST is gebaseerd op zes architectuurbeperkingen geformuleerd door Fielding. Het naleven van deze beperkingen garandeert schaalbaarheid, prestaties en eenvoudige integratie. Elk principe lost een specifiek probleem van gedistribueerde systemen op — van de noodzaak van caching tot beveiligingseisen. Laten we elk principe in detail bekijken.

Het principe Uniform Interface omvat bovendien vier sub-beperkingen: identificatie van resources via URI, manipulatie van resources via representaties, zelfbeschrijvende berichten en HATEOAS (hypermedia als engine van applicatiestatus). De laatste sub-beperking wordt in de praktijk vaak genegeerd — de meeste moderne REST API's implementeren HATEOAS niet volledig, wat leidt tot discussies over de vraag of een dergelijke API ‘echt’ RESTful is.

Het principe Stateless — een van de belangrijkste voor schaalbaarheid. Het ontbreken van sessies op de server betekent dat elk serverexemplaar elk verzoek kan verwerken. Dit vereenvoudigt horizontale schaalbaarheid: het volstaat om nieuwe servers achter de load balancer toe te voegen. Voor mobiele apps betekent stateless ook dat een verzoek naar elke CDN-server kan worden gestuurd, wat cruciaal is voor wereldwijde beschikbaarheid.

HTTP-methoden in REST

Elke HTTP-methode in REST API komt overeen met een specifieke bewerking op een resource: GET voor lezen, POST voor aanmaken, PUT voor volledige update, PATCH voor gedeeltelijke update, DELETE voor verwijderen. Idempotentie van methoden is een belangrijk kenmerk: GET, PUT, DELETE zijn idempotent (herhaalde uitvoering geeft hetzelfde resultaat), POST en PATCH niet. Dit is belangrijk voor het afhandelen van netwerkfouten, wanneer de client niet weet of het verzoek de server heeft bereikt.

• GET — ophalen van een resource of lijst van resources. Idempotent, wijzigt serverstatus niet
• POST — aanmaken van een nieuwe resource. Niet idempotent, elke aanroep maakt een nieuwe resource
• PUT — volledige vervanging van een resource. Idempotent, herhaalde aanroep wijzigt status na eerste niet
• PATCH — gedeeltelijke update van een resource. Gedeeltelijk idempotent (afhankelijk van implementatie)
• DELETE — verwijderen van een resource. Idempotent, herhaalde verwijdering retourneert 404, geen fout

HTTP-statuscodes zijn een integraal onderdeel van REST API. Elke code heeft een specifieke betekenis: 200 OK voor succesvolle GET, 201 Created voor POST, 204 No Content voor DELETE zonder antwoordbody, 400 Bad Request bij ongeldige gegevens, 401 Unauthorized bij afwezigheid van authenticatie, 404 Not Found bij afwezigheid van resource. Correct gebruik van statuscodes maakt de API zelfdocumenterend en vereenvoudigt debugging.

Gegevensformaten: JSON en andere

JSON (JavaScript Object Notation) — het belangrijkste formaat voor gegevensoverdracht in REST API. De populariteit ervan wordt verklaard door eenvoud, menselijke leesbaarheid en native ondersteuning in JavaScript. JSON wordt verzonden met de header Content-Type: application/json. Alternatieven zijn XML (omvangrijk, verouderend), YAML (handig voor configuratie, zeldzamer voor API) en Protocol Buffers (binair, efficiënt voor systemen met hoge belasting).

De structuur van een JSON-object in REST API bevat meestal de velden id, type en resource-attributen. Voor collecties wordt een JSON-array met paginering-metadata gebruikt. Moderne REST API's volgen de JSON:API-specificatie (jsonapi.org) of JSON Schema voor validatie van antwoorden. Het gebruik van een uniform gegevensformaat vereenvoudigt de ontwikkeling van clientbibliotheken en het genereren van documentatie.

Voorbeeld van een JSON-antwoord voor een gebruikerslijst:

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

De keuze van het gegevensoverdrachtsformaat beïnvloedt de prestaties van de mobiele app. JSON wordt via GZIP met 70–80% gecomprimeerd, wat het acceptabel maakt voor de meeste scenario's. Voor realtime-applicaties met grote hoeveelheden gegevens (streaming, games) wordt aanbevolen over te stappen op binaire protocollen of WebSocket te gebruiken in combinatie met Protocol Buffers.

Voorbeelden van REST API-verzoeken

Laten we praktische voorbeelden bekijken van werken met REST API aan de kant van de mobiele app. Als voorbeeld nemen we een API voor het werken met bestellingen in een online winkel. Voor elke HTTP-methode worden het verzoek en het verwachte serverantwoord getoond. De voorbeelden tonen de typische structuur van een RESTful API die in mobiele ontwikkeling wordt gebruikt.

GET — ophalen van bestellijst

Verzoek om alle bestellingen van een gebruiker op te halen met paginering. Het antwoord bevat een array van bestellingsobjecten en meta-informatie voor paginanavigatie. De parameters page en per_page worden via query string doorgegeven.

// Retrofit-interface voor 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 — aanmaken van nieuwe bestelling

Aanmaken van een nieuwe bestelling via een POST-verzoek. De server retourneert status 201 Created en het aangemaakte object in de antwoordbody. Belangrijk: het aanmaken gebeurt op de collectie /api/v1/orders, niet op een specifieke resource — dit is een standaard RESTful-patroon.

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

// Voorbeeld van verzoekbody
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — verwijderen van bestelling

Verwijderen van een resource gebeurt met de DELETE-methode op de specifieke URL van de bestelling. Succesvol verwijderen retourneert 204 No Content. Idempotentie van DELETE betekent dat een herhaald verzoek naar dezelfde URL 404 Not Found retourneert, wat correct wordt afgehandeld aan de clientzijde.

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

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

Deze voorbeelden tonen de typische implementatie van REST API aan de Android-kant met behulp van Retrofit en Kotlin Coroutines. Voor iOS-apps vervullen URLSession of de Alamofire-bibliotheek in combinatie met Codable-protocollen een vergelijkbare rol. De REST API-structuur blijft hetzelfde ongeacht het platform — alleen de manier van uitvoeren van verzoeken verandert.

RESTful API-ontwerp: praktische aanbevelingen

Het ontwerpen van een kwalitatief RESTful API vereist het volgen van conventies die de API intuïtief maken voor ontwikkelaars. Resources moeten worden benoemd met meervoudige zelfstandige naamwoorden (/users, /orders, /products), HTTP-methoden moeten bewerkingen weerspiegelen en URL's moeten de hiërarchische structuur tonen. Fouten moeten een gestandaardiseerde JSON met code en bericht retourneren, niet alleen een HTTP-status. Het naleven van deze conventies verlaagt de toegangsdrempel voor nieuwe ontwikkelaars en vereenvoudigt integratie.

• Naamgeving van resources — meervoud, kebab-case: /api/v1/user-orders, niet /api/v1/getUserOrders
• Filteren en sorteren — via query-parameters: ?status=active&sort=created_at:desc
• Paginering — cursor-based voor grote sets, page-based voor kleine
• Versionering — via URL (/api/v2/) of header Accept-Version
• Fouten — uniform formaat: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — headers X-RateLimit-Remaining en Retry-After

Een veelgemaakte fout bij het ontwerpen van REST API is overmatige nesting van resources. In plaats van /users/1/orders/5/items/3 is het beter een platte structuur met query-parameters te gebruiken: /items?order_id=5&user_id=1. Dit vereenvoudigt caching, vereist geen ondersteuning van lange paden op de server en is eenvoudiger te documenteren. Een platte architectuur is ook beter compatibel met graph-gebaseerde verzoeken bij een overstap naar GraphQL in de toekomst.

Beveiliging van REST API wordt gerealiseerd via authenticatie (JWT, OAuth 2.0) en autorisatie op resourceniveau. Elk verzoek moet controleren of de gebruiker toegang heeft tot de gevraagde resource. HTTPS is verplicht — zonder encryptie worden tokens en gegevens in platte tekst verzonden. Voor mobiele apps wordt aanbevolen OAuth 2.0 met PKCE (Proof Key for Code Exchange) te gebruiken voor het veilig verkrijgen van tokens.

Versionering en caching

Versionering van REST API is noodzakelijk voor achterwaartse compatibiliteit bij wijzigingen. De meest voorkomende benaderingen: versie in URL (/api/v1/orders), versie in header (Accept: application/vnd.myapi.v1+json) en versie in query-parameter (?api_version=1). URL-versionering is de populairste methode omdat deze duidelijk zichtbaar is in logs en documentatie. Het schendt echter het REST-principe van een unieke resource-URL.

Caching in REST API wordt gerealiseerd via HTTP-headers Cache-Control, ETag en Last-Modified. GET-verzoeken die als cachebaar zijn gemarkeerd, kunnen worden bediend uit de cache van de browser of proxy zonder de server aan te roepen. Voor mobiele apps is caching bijzonder belangrijk — het vermindert het dataverbruik en versnelt de weergave van eerder geladen gegevens bij een slechte verbinding. ETag is een hash van de antwoordinhoud: de client stuurt deze in If-None-Match en de server retourneert 304 Not Modified als de gegevens niet zijn gewijzigd.

Moderne alternatieven voor REST API zijn GraphQL (flexibele gegevensselectie door de client) en gRPC (binair protocol op HTTP/2 voor microservices). REST blijft echter de belangrijkste standaard voor openbare API's vanwege zijn eenvoud, universaliteit en brede ondersteuning van tools. De keuze tussen REST en alternatieven hangt af van de specifieke projectvereisten: complexiteit van verzoeken, gegevensvolume, vereisten voor realtime-updates.