REST API: Was es ist, HTTP-Methoden und Funktionsprinzip in mobilen Anwendungen

Was ist REST API?

REST API (Representational State Transfer API) ist ein Architekturstil, der von Roy Fielding in seiner Doktorarbeit im Jahr 2000 vorgeschlagen wurde. Er definiert eine Reihe von Einschränkungen und Prinzipien für das Design von Netzwerkprotokollen. Eine API, die diese Einschränkungen einhält, wird als RESTful bezeichnet. REST ist kein Protokoll oder Standard — es ist ein architektonischer Ansatz, der vorhandene Protokolle (hauptsächlich HTTP) für den Datenaustausch zwischen Client und Server nutzt.

Die Kernidee von REST ist die ressourcenorientierte Architektur. Anstatt Methoden auf dem Server aufzurufen (wie in SOAP oder RPC), arbeitet der Client mit Ressourcen: er ruft Listen ab, erstellt neue, aktualisiert oder löscht sie. Jede Ressource ist eine Domänenentität: Benutzer, Bestellung, Produkt, Artikel. Eine Ressource hat einen Zustand, der dem Client in einem standardisierten Format, in der Regel JSON, übermittelt wird. Der Server speichert den Client-Status nicht zwischen den Anfragen — dies ist das Stateless-Prinzip, eine Kernanforderung von REST.

Hauptmerkmale von REST API:

• Stateless — jede Anfrage des Clients enthält alle für die Verarbeitung erforderlichen Informationen
• Cacheable — Serverantworten müssen explizit als cachebar oder nicht cachebar gekennzeichnet werden
• Layered system — die Architektur kann Zwischenserver, Lastenausgleicher, Proxys umfassen
• Uniform interface — eine einheitliche Interaktionsschnittstelle über HTTP-Methoden, URLs und Statuscodes

Prinzipien der REST-Architektur

REST basiert auf sechs von Fielding formulierten architektonischen Einschränkungen. Die Einhaltung dieser Einschränkungen gewährleistet Skalierbarkeit, Leistung und Integrationsfreundlichkeit. Jedes Prinzip löst ein spezifisches Problem verteilter Systeme — von Caching-Anforderungen bis hin zu Sicherheitsanforderungen. Betrachten wir jedes Prinzip im Detail.

Das Prinzip Uniform Interface umfasst zusätzlich vier Untereinschränkungen: Ressourcenidentifikation über URI, Ressourcenmanipulation durch Darstellungen, selbstbeschreibende Nachrichten und HATEOAS (Hypermedia als Engine of Application State). Die letzte Untereinschränkung wird in der Praxis oft ignoriert — die meisten modernen REST-APIs implementieren HATEOAS nicht vollständig, was zu Diskussionen darüber führt, ob eine solche API „wirklich“ RESTful ist.

Das Stateless-Prinzip ist eines der wichtigsten für die Skalierung. Das Fehlen von Sitzungen auf dem Server bedeutet, dass jede Serverinstanz jede Anfrage verarbeiten kann. Dies vereinfacht die horizontale Skalierung: Es müssen nur neue Server hinter einem Lastenausgleicher hinzugefügt werden. Für mobile Anwendungen bedeutet Stateless auch, dass eine Anfrage an jeden CDN-Server gesendet werden kann, was für die globale Verfügbarkeit entscheidend ist.

HTTP-Methoden in REST

Jede HTTP-Methode in REST API entspricht einer bestimmten Operation auf einer Ressource: GET zum Lesen, POST zum Erstellen, PUT zur vollständigen Aktualisierung, PATCH zur teilweisen Aktualisierung, DELETE zum Löschen. Die Idempotenz der Methoden ist eine Schlüsseleigenschaft: GET, PUT, DELETE sind idempotent (wiederholte Ausführung liefert dasselbe Ergebnis), POST und PATCH nicht. Dies ist wichtig für die Behandlung von Netzwerkfehlern, wenn der Client nicht weiß, ob die Anfrage den Server erreicht hat.

• GET — Abrufen einer Ressource oder Ressourcenliste. Idempotent, ändert den Serverzustand nicht
• POST — Erstellen einer neuen Ressource. Nicht idempotent, jeder Aufruf erstellt eine neue Ressource
• PUT — vollständiger Ersatz einer Ressource. Idempotent, wiederholte Aufrufe ändern den Zustand nach dem ersten nicht
• PATCH — teilweise Aktualisierung einer Ressource. Teilweise idempotent (abhängig von der Implementierung)
• DELETE — Löschen einer Ressource. Idempotent, wiederholtes Löschen gibt 404 zurück, keinen Fehler

HTTP-Statuscodes sind ein integraler Bestandteil von REST API. Jeder Code hat eine bestimmte Bedeutung: 200 OK für erfolgreiches GET, 201 Created für POST, 204 No Content für DELETE ohne Antwortkörper, 400 Bad Request bei ungültigen Daten, 401 Unauthorized bei fehlender Authentifizierung, 404 Not Found bei fehlender Ressource. Die korrekte Verwendung von Statuscodes macht die API selbstdokumentierend und vereinfacht die Fehlersuche.

Datenformate: JSON und andere

JSON (JavaScript Object Notation) ist das primäre Datenformat für die Datenübertragung in REST API. Seine Popularität verdankt es seiner Einfachheit, Lesbarkeit und nativen Unterstützung in JavaScript. JSON wird mit dem Header Content-Type: application/json übertragen. Alternativen umfassen XML (umständlich, veraltend), YAML (praktisch für Konfiguration, seltener für APIs) und Protocol Buffers (binär, effizient für hochbelastete Systeme).

Die Struktur eines JSON-Objekts in REST API umfasst in der Regel die Felder id, type sowie Ressourcenattribute. Für Sammlungen wird ein JSON-Array mit Paginierungsmetadaten verwendet. Moderne REST-APIs folgen der JSON:API-Spezifikation (jsonapi.org) oder JSON Schema zur Antwortvalidierung. Die Verwendung eines einheitlichen Datenformats vereinfacht die Entwicklung von Client-Bibliotheken und die Dokumentationserstellung.

Beispiel einer JSON-Antwort für eine Benutzerliste:

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

Die Wahl des Datenübertragungsformats beeinflusst die Leistung mobiler Anwendungen. JSON wird durch GZIP um 70-80% komprimiert, was es für die meisten Szenarien akzeptabel macht. Für Echtzeitanwendungen mit großen Datenmengen (Streaming, Spiele) wird empfohlen, auf binäre Protokolle umzusteigen oder WebSocket in Kombination mit Protocol Buffers zu verwenden.

Beispiele für REST-API-Anfragen

Sehen wir uns praktische Beispiele für die Arbeit mit der REST API auf der Seite der mobilen Anwendung an. Als Beispiel nehmen wir eine API für die Arbeit mit Bestellungen in einem Online-Shop. Für jede HTTP-Methode werden eine Anfrage und die erwartete Serverantwort gezeigt. Die Beispiele demonstrieren die typische RESTful-API-Struktur, die in der mobilen Entwicklung verwendet wird.

GET — Abrufen einer Bestellliste

Eine Anfrage zum Abrufen aller Benutzerbestellungen mit Paginierung. Die Antwort enthält ein Array von Bestellungsobjekten und Metainformationen für die Seitennavigation. Die Parameter page und per_page werden über die Query-String übergeben.

// Retrofit-Schnittstelle für 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 — Erstellen einer neuen Bestellung

Erstellen einer neuen Bestellung über eine POST-Anfrage. Der Server gibt den Status 201 Created und das erstellte Objekt im Antwortkörper zurück. Wichtig: Die Erstellung erfolgt auf der Sammlung /api/v1/orders, nicht auf einer spezifischen Ressource — dies ist das standardmäßige RESTful-Muster.

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

// Beispiel für Anforderungskörper
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — Löschen einer Bestellung

Das Löschen einer Ressource erfolgt mit der DELETE-Methode auf der spezifischen Bestell-URL. Erfolgreiches Löschen gibt 204 No Content zurück. Die Idempotenz von DELETE bedeutet, dass eine wiederholte Anfrage an dieselbe URL 404 Not Found zurückgibt, was clientseitig korrekt behandelt wird.

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

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

Diese Beispiele zeigen eine typische REST-API-Implementierung auf der Android-Seite unter Verwendung von Retrofit und Kotlin Coroutines. Für iOS-Anwendungen übernehmen URLSession oder die Alamofire-Bibliothek in Verbindung mit Codable-Protokollen eine ähnliche Rolle. Die REST-API-Struktur bleibt unabhängig von der Plattform gleich — es ändert sich nur die Art und Weise der Anfrageausführung.

RESTful-API-Design: Praktische Empfehlungen

Das Design einer qualitativ hochwertigen RESTful-API erfordert die Einhaltung von Konventionen, die die API für Entwickler intuitiv machen. Ressourcen sollten mit Substantiven im Plural (/users, /orders, /products) benannt werden, HTTP-Methoden sollten Operationen widerspiegeln und URLs sollten die Verschachtelungshierarchie darstellen. Fehler sollten ein standardisiertes JSON mit Code und Nachricht zurückgeben, nicht nur einen HTTP-Status. Die Einhaltung dieser Konventionen senkt die Einstiegshürde für neue Entwickler und vereinfacht die Integration.

• Ressourcenbenennung — Plural, Kebab-Case: /api/v1/user-orders, nicht /api/v1/getUserOrders
• Filterung und Sortierung — über Query-Parameter: ?status=active&sort=created_at:desc
• Paginierung — Cursor-basiert für große Datensätze, seitenbasiert für kleine
• Versionierung — über URL (/api/v2/) oder Accept-Version-Header
• Fehler — einheitliches Format: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Ratenbegrenzung — X-RateLimit-Remaining- und Retry-After-Header

Ein häufiger Fehler beim Design einer REST-API ist übermäßige Ressourcenverschachtelung. Statt /users/1/orders/5/items/3 ist es besser, eine flache Struktur mit Query-Parametern zu verwenden: /items?order_id=5&user_id=1. Dies vereinfacht das Caching, erfordert keine langen Pfade auf dem Server und ist leichter zu dokumentieren. Die flache Architektur ist auch besser kompatibel mit graphbasierten Abfragen bei einem zukünftigen Wechsel zu GraphQL.

Die Sicherheit der REST-API wird durch Authentifizierung (JWT, OAuth 2.0) und Autorisierung auf Ressourcenebene implementiert. Jede Anfrage muss überprüfen, ob der Benutzer Zugriff auf die angeforderte Ressource hat. HTTPS ist obligatorisch — ohne Verschlüsselung werden Token und Daten im Klartext übertragen. Für mobile Anwendungen wird die Verwendung von OAuth 2.0 mit PKCE (Proof Key for Code Exchange) zur sicheren Token-Erlangung empfohlen.

Versionierung und Caching

Die Versionierung der REST-API ist für die Abwärtskompatibilität bei Änderungen erforderlich. Die gängigsten Ansätze sind: Version in der URL (/api/v1/orders), Version im Header (Accept: application/vnd.myapi.v1+json) und Version im Query-Parameter (?api_version=1). Die URL-Versionierung ist die beliebteste Methode, da sie in Logs und Dokumentation explizit sichtbar ist. Sie verstößt jedoch gegen das REST-Prinzip einer einzigen URL pro Ressource.

Caching in REST-API wird über HTTP-Header Cache-Control, ETag und Last-Modified implementiert. GET-Anfragen, die als cachebar markiert sind, können aus dem Browser- oder Proxy-Cache bedient werden, ohne den Server zu kontaktieren. Für mobile Anwendungen ist Caching besonders wichtig — es reduziert den Datenverbrauch und beschleunigt die Anzeige zuvor geladener Daten bei schlechter Konnektivität. ETag ist ein Hash des Antwortinhalts: Der Client sendet ihn in If-None-Match, und der Server gibt 304 Not Modified zurück, wenn sich die Daten nicht geändert haben.

Moderne Alternativen zur REST-API umfassen GraphQL (flexibler clientseitiger Datenabruf) und gRPC (binäres Protokoll auf HTTP/2 für Microservices). REST bleibt jedoch aufgrund seiner Einfachheit, Universalität und umfangreichen Tool-Unterstützung der primäre Standard für öffentliche APIs. Die Wahl zwischen REST und Alternativen hängt von den spezifischen Projektanforderungen ab: Abfragekomplexität, Datenvolumen, Anforderungen an Echtzeit-Updates.