REST [Representational State Transfer] -Service

REST

REST, kurz für Representational State Transfer, ist ein Architektur-Stil für die Erstellung von Webservices. REST werden die Daten als Ressourcen betrachtet, die durch eindeutige URIs (Uniform Resource Identifiers) identifiziert werden.

REST-Methoden

REST-Methoden sind Werkzeuge zur Manipulation von Ressourcen. Sie sind Bestandteile einer HTTP-Anfrage, die angeben, welche Aktion mit einer bestimmten Ressource ausgeführt werden soll. Jede Methode hat eine spezifische Bedeutung und wird in bestimmten Szenarien eingesetzt. 

Die wichtigsten REST-Methoden im Überblick:

• GET:

  • Zweck: Zum Abrufen einer Darstellung einer bestimmten Ressource.

  • Veränderung des Servers: Keine.

  • Beispiel: GET /users/1 (Gibt die Informationen zum Benutzer mit der ID 1 zurück.)

• POST:

  • Zweck: Zum Erstellen einer neuen Ressource unter einer gegebenen Ressource.

  • Veränderung des Servers: Fügt eine neue Ressource hinzu.

  • Beispiel: POST /todos (Erstellt ein neues To-Do in der To-Do-Liste.)

• PUT:

  • Zweck: Zum Ersetzen einer gesamten Ressource.

  • Veränderung des Servers: Ersetzt die gesamte Ressource durch die in der Anfrage enthaltenen Daten.

  • Beispiel: PUT /users/1 (Ersetzt alle Informationen des Benutzers mit der ID 1.)

• DELETE:

  • Zweck: Zum Löschen einer Ressource.

  • Veränderung des Servers: Entfernt die angegebene Ressource.

  • Beispiel: DELETE /todos/2 (Löscht das To-Do mit der ID 2.)

• PATCH:

  • Zweck: Zum Teilweisen Aktualisieren einer Ressource.

  • Veränderung des Servers: Ändert nur bestimmte Attribute einer Ressource.

  • Beispiel: PATCH /users/1 (Ändert nur den Namen des Benutzers mit der ID 1.)

Weitere, weniger häufig verwendete Methoden:

• HEAD: Die HEAD-Methode ist eine spezielle Variante der GET-Methode. Im Gegensatz zu GET, das den gesamten Inhalt einer Ressource zurückgibt, liefert HEAD nur die Metadaten der Ressource. Dazu gehören beispielsweise:

• HTTP-Statuscode: Zeigt an, ob die Ressource existiert (200 OK) oder nicht (404 Not Found).

• MIME-Type: Gibt den Inhaltstyp der Ressource an (z.B. text/html, application/json).

• Länge der Ressource: Die Größe der Ressource in Bytes.

• Letzte Änderung: Das Datum und die Uhrzeit der letzten Änderung der Ressource.

• OPTIONS: Gibt die für eine Ressource unterstützten HTTP-Methoden zurück.

REST URL

Eine REST URL (REST Uniform Resource Locator) ist im Grunde die Webadresse, unter der eine bestimmte Ressource in einer REST API angesprochen wird. Sie besteht aus einem Basis-URL und einem Pfad, der die Hierarchie der Ressourcen widerspiegelt. Durch die Kombination der URL mit einer HTTP-Methode wird eine spezifische Aktion ausgeführt. 

Die einzelnen Bestandteile der URL:

• http:

  • Dies ist das Protokoll, über das die Anfrage gesendet wird. HTTP (Hypertext Transfer Protocol) ist das Standardprotokoll für das Web. Es definiert, wie Daten zwischen einem Client (z.B. deinem Browser) und einem Server ausgetauscht werden.

• localhost:

  • Dies ist der Hostname oder die IP-Adresse des Servers. In diesem Fall wird der Server lokal auf deinem eigenen Computer ausgeführt.

• 1234:

  • Dies ist der Port, an dem der Server lauscht. Ports sind numerische Werte, die verwendet werden, um verschiedene Dienste auf einem Computer zu unterscheiden.

• hrservices:

  • Dies ist der Kontext oder der Bereich der Anwendung. Es zeigt an, dass die Anfrage an den Teil der Anwendung gerichtet ist, der sich mit Personaldienstleistungen (Human Resources Services) befasst.

• v1:

  • Dies ist die Version der API. Durch die Versionierung können Änderungen an der API vorgenommen werden, ohne bestehende Anwendungen zu beeinträchtigen.

• users:

  • Dies ist die Ressource, auf die zugegriffen wird. In diesem Fall sind es Benutzerdaten.

• {id}:

  • Dies ist ein Platzhalter für eine spezifische Benutzer-ID. Er wird durch einen tatsächlichen Wert ersetzt, wenn die Anfrage ausgeführt wird (z.B. http://localhost:1234/hrservices/v1/users/123).

Welche HTTP-Methode würde man typischerweise für diese URL verwenden?

• GET: Um die Informationen eines bestimmten Benutzers abzurufen.
  Beispiel: GET http://localhost:1234/hrservices/v1/users/123

• PUT: Um die Informationen eines bestimmten Benutzers zu aktualisieren.
  
  

• DELETE: Um einen bestimmten Benutzer zu löschen.

REST API Key: Der Zugangsschlüssel 

Ein REST API Key ist ein eindeutiger Bezeichner, der zur Authentifizierung bei einer REST API dient. Er ermöglicht es, den Aufrufenden einer API zu identifizieren und zu autorisieren.

Es gibt verschiedene Möglichkeiten, den API Key in einer Anfrage anzugeben:

• Im Header:

  • Authorization: Bearer YOUR_API_KEY

• Als Query-Parameter:

  • https://api.example.com/users?api_key=YOUR_API_KEY

• Im Request Body:

  • Je nach API-Design kann der API Key auch im Request Body übertragen werden.
    
    

Der API Key erfüllt folgende Funktionen:

• • Authentifizierung: Durch den Vergleich des in der Anfrage enthaltenen API-Keys mit einer Liste bekannter, gültiger Schlüssel kann der Server überprüfen, ob der Anfragende berechtigt ist, auf die API zuzugreifen. Es ist wie ein Passwort, das dem Server signalisiert: "Ich bin es, lass mich rein!"

  • Berechtigungen: API-Keys können mit unterschiedlichen Berechtigungen verknüpft sein. So kann ein API-Key beispielsweise nur Lesezugriff auf bestimmte Daten haben, während ein anderer sowohl Lese- als auch Schreibzugriff besitzt.

  • Tracking und Analyse: API-Keys können verwendet werden, um den Zugriff auf die API zu verfolgen und zu analysieren. So können beispielsweise Informationen darüber gesammelt werden, welche Anwendungen die API am häufigsten nutzen oder welche Funktionen besonders beliebt sind.

  • Identifikation: Der API-Key dient als eindeutige Kennung für eine bestimmte Anwendung oder einen bestimmten Benutzer. Wenn eine Anfrage an eine API gesendet wird, wird der API-Key in den Anfrageheader eingefügt. Der Server kann anhand dieses Schlüssels die Identität des Anfragenden feststellen.

HTTP-Statuscode

HTTP-Statuscodes sind ein fundamentales Konzept in RESTful APIs. Sie liefern wertvolle Informationen über den Status einer Anfrage und sind ein unverzichtbares Werkzeug für die Entwicklung robuster und interoperabler Anwendungen.

HTTP-Statuscodes sind dreistellige Zahlen, die in einer Antwortnachricht von einem Server an einen Client gesendet werden. Sie geben an, ob die Anfrage erfolgreich bearbeitet wurde oder ob ein Fehler aufgetreten ist.  Der Statuscode unterstützt:

• Transparenz: Sie machen den Zustand der Anfrage für den Client transparent.

• Fehlerbehandlung: Sie ermöglichen es dem Client, auf Fehler zu reagieren und entsprechende Maßnahmen zu ergreifen.

• Caching: Einige Statuscodes (z.B. 304 Not Modified) sind für Caching-Mechanismen relevant.

• Standardisierung: Sie bieten einen standardisierten Weg, um den Status einer Anfrage zu kommunizieren.

In Bezug auf REST-Services spielen HTTP-Statuscodes eine entscheidende Rolle, da sie dem Client Informationen über den Erfolg oder Misserfolg einer Anfrage liefern.

Kategorien von HTTP-Statuscodes

Die wichtigsten Kategorien von HTTP-Statuscodes im Zusammenhang mit REST:

• 2xx (Erfolg): Die Anfrage wurde erfolgreich bearbeitet. Beispiele: 200 OK, 201 Created.

• 3xx (Weiterleitung): Der Client muss eine weitere Aktion ausführen, um die gewünschte Ressource zu erhalten. Beispiele: 301 Moved Permanently, 302 Found.

• 4xx (Clientfehler): Der Client hat einen Fehler gemacht. Beispiele: 400 Bad Request, 401 Unauthorized, 404 Not Found.

• 5xx (Serverfehler): Der Server konnte die Anfrage nicht bearbeiten. Beispiele: 500 Internal Server Error, 503 Service Unavailable.

Beispiele für HTTP-Statuscodes in REST-Services:

• GET /users/123 (Abrufen eines Benutzers mit der ID 123):

  • 200 OK: Der Benutzer wurde erfolgreich gefunden und zurückgegeben.

  • 404 Not Found: Der Benutzer mit der ID 123 existiert nicht.

• POST /users (Erstellen eines neuen Benutzers):

  • 201 Created: Der Benutzer wurde erfolgreich erstellt.

  • 400 Bad Request: Die übermittelten Daten sind ungültig.

• PUT /users/123 (Aktualisieren eines Benutzers):

  • 200 OK: Der Benutzer wurde erfolgreich aktualisiert.

  • 404 Not Found: Der Benutzer mit der ID 123 existiert nicht.

Fehler-Ressourcen

Wenn man von "speziellen Fehler-Ressourcen" im Kontext von REST-APIs spricht, meint man in der Regel, dass für bestimmte Fehlerarten eigene Ressourcen definiert werden, die beim Auftreten dieses Fehlers zurückgegeben werden. 

Anstatt nur einen generischen HTTP-Statuscode zurückzugeben, können in der Fehler-Ressource spezifische Informationen über den Fehler enthalten sein, wie z.B.:

• Eine ausführliche Fehlermeldung

• Ein Fehlercode

• Zusätzliche Kontextinformationen

• Vorschläge zur Fehlerbehebung

Beispiel:

Angenommen, eine REST-API für einen Online-Shop hat eine Ressource "/users/login". Wenn ein Benutzer versucht, sich mit falschen Anmeldeinformationen anzumelden, könnte die API folgende JSON-Antwort zurückgeben:

JSON

{

  "error": "invalid_credentials",

  "message": "Die eingegebenen Anmeldeinformationen sind ungültig.",

  "solution": "Bitte überprüfen Sie Ihre E-Mail-Adresse und Ihr Passwort."

}

Hier ist die Antwort nicht nur ein einfacher 401 Unauthorized Statuscode, sondern eine strukturierte JSON-Antwort mit zusätzlichen Informationen, die dem Client helfen, den Fehler zu verstehen und zu beheben.