REST-API: Grundlagen und Prinzipien

• REST API (Representational State Transfer Application Programming Interface) ist ein Architekturstil zum Aufbau vernetzter Anwendungen.
• Es basiert auf einem zustandslosen, Client-Server-fähigen und zwischenspeicherbaren Kommunikationsprotokoll, wobei in fast allen Fällen das HTTP-Protokoll verwendet wird.
• REST-APIs ermöglichen verschiedenen Softwaresystemen die standardisierte Kommunikation und den Datenaustausch über das Internet.

Hauptprinzipien von REST

• Client-Server: Client und Server arbeiten unabhängig voneinander; Clients initiieren Anfragen, und Server verarbeiten diese und senden Antworten zurück.
• Zustandslos: Jede Anfrage von einem Client an einen Server muss alle Informationen enthalten, die zum Verständnis der Anfrage erforderlich sind, und darf keinen gespeicherten Kontext auf dem Server nutzen. Der Sitzungsstatus wird vollständig auf dem Client verwaltet.
• Zwischenspeicherbar: Antworten sollten zwischenspeicherbar sein, um die Effizienz zu verbessern. Clients können zwischengespeicherte Antworten für ähnliche Anfragen wiederverwenden.
• Schichtsystem: Die Architektur kann aus mehreren Schichten bestehen, die die Interaktion zwischen Client und Server nicht beeinträchtigen.
• Einheitliche Schnittstelle: Diese Einschränkung ist grundlegend für das Design jeder RESTful-API und vereinfacht und entkoppelt die Architektur, wodurch sich jedes Teil unabhängig weiterentwickeln kann.
• Code on Demand (optional): Server können die Funktionalität eines Clients erweitern, indem sie ausführbaren Code übertragen.

Details zur einheitlichen Schnittstelle

• Identifizierung von Ressourcen: Jede Ressource sollte über einen URI (Uniform Resource Identifier) eindeutig identifizierbar sein.
• Manipulation von Ressourcen durch Darstellungen: Clients bearbeiten Ressourcen durch Darstellungen (z. B. JSON, XML), die genügend Informationen für den Server bereitstellen, um die Ressource zu ändern oder zu löschen.
• Selbstbeschreibende Nachrichten: Jede Nachricht enthält genügend Informationen, um zu beschreiben, wie die Nachricht verarbeitet werden soll (z. B. unter Verwendung von Medientypen).
• Hypermedia as the Engine of Application State (HATEOAS): Clients entdecken und nutzen die API über Hypermedia-Links, die in den Antworten enthalten sind. Dies ermöglicht es Clients, dynamisch mit der API zu navigieren und zu interagieren.

HTTP-Methoden

• GET: Ruft eine Ressource ab. Sollte keine Nebenwirkungen haben (idempotent).
• POST: Erstellt eine neue Ressource.
• PUT: Aktualisiert eine vorhandene Ressource vollständig.
• PATCH: Ändert eine vorhandene Ressource teilweise.
• DELETE: Löscht eine Ressource.

Ressourcen und URIs

• Ressourcen sind die wichtigsten Abstraktionen von Informationen.
• Jede Ressource wird durch einen URI identifiziert.
• URIs sind so konzipiert, dass sie klar und vorhersehbar sind.
• Beispiel: https://api.example.com/users (Sammlung von Benutzern), https://api.example.com/users/123 (spezifischer Benutzer mit ID 123).

Datenformate

• JSON (JavaScript Object Notation) ist aufgrund seiner Einfachheit und einfachen Analyse das gebräuchlichste Datenformat.
• XML (Extensible Markup Language) ist ein weiteres Format, das in modernen APIs jedoch weniger häufig verwendet wird als JSON.

Statuscodes

• 200 OK: Anfrage war erfolgreich.
• 201 Erstellt: Ressource wurde erfolgreich erstellt.
• 204 Kein Inhalt: Anfrage war erfolgreich, es gibt jedoch keinen Inhalt zurückzugeben.
• 400 Ungültige Anfrage: Anfrage konnte aufgrund einer fehlerhaften Syntax nicht verstanden werden.
• 401 Nicht autorisiert: Authentifizierung ist erforderlich.
• 403 Verboten: Der Server hat die Anfrage verstanden, verweigert jedoch die Autorisierung.
• 404 Nicht gefunden: Ressource wurde nicht gefunden.
• 500 Interner Serverfehler: Allgemeine Fehlermeldung, wenn eine unerwartete Bedingung aufgetreten ist.

Vorteile von REST-APIs

• Skalierbarkeit: Die Zustandslosigkeit ermöglicht eine einfache Skalierung serverseitiger Komponenten.
• Flexibilität: REST-APIs können verschiedene Arten von Clients bedienen.
• Interoperabilität: Verwendet offene Standards wie HTTP und JSON, was die Interoperabilität zwischen verschiedenen Systemen und Plattformen erleichtert.
• Einfachheit: Leicht zu verstehen und zu implementieren.
• Unabhängige Entwicklung: Die Client- und Serverseiten können sich separat entwickeln.

HATEOAS (Hypermedia as the Engine of Application State)

• HATEOAS ermöglicht es Clients, verfügbare Ressourcen und Aktionen dynamisch zu ermitteln.
• API-Antworten enthalten Hyperlinks, die Clients leiten.
• Entkoppelt Client und Server, indem es fest codierte URLs vom Client entfernt.
• Unterstützt die API-Entwicklung, ohne Clients zu beeinträchtigen.
• Beispiel: Eine Antwort kann Links zum Bearbeiten oder Löschen der abgerufenen Ressource enthalten.

API-Dokumentation

• Entscheidend für Entwickler, um zu verstehen, wie die API verwendet wird.
• Zu den gängigen Tools gehören OpenAPI (Swagger) und RAML.
• Die Dokumentation sollte URI-Endpunkte, Anfrage-/Antwortformate und Authentifizierungsanforderungen enthalten.

Authentifizierung und Autorisierung

• Die Authentifizierung überprüft die Identität des Clients.
• Die Autorisierung bestimmt, auf welche Ressourcen der Client Zugriff hat.
• Übliche Methoden umfassen:
  • API-Schlüssel: Einfache Authentifizierung mit einem Schlüssel.
  • OAuth 2.0: Delegiertes Autorisierungs-Framework, das Drittanbieteranwendungen eingeschränkten Zugriff auf einen HTTP-Dienst ermöglicht.
  • JWT (JSON Web Tokens): Kompakte, URL-sichere Möglichkeit, Ansprüche darzustellen, die zwischen zwei Parteien übertragen werden sollen.

API-Versionierung

• Ermöglicht die Weiterentwicklung der API, ohne bestehende Clients zu beeinträchtigen.
• Die Versionierung kann implementiert werden durch:
  • URI-Pfad (z. B. /v1/users)
  • Header (z. B. Accept: application/vnd.example.v1+json)

Best Practices für das REST-API-Design

• Verwenden Sie Substantive anstelle von Verben in URIs (z. B. /users anstelle von /getUsers).
• Verwenden Sie HTTP-Methoden korrekt (z. B. GET zum Abrufen, POST zum Erstellen).
• Stellen Sie klare und informative Fehlermeldungen bereit.
• Implementieren Sie die Paginierung für große Datensätze.
• Sichern Sie die API mithilfe geeigneter Authentifizierungs- und Autorisierungsmechanismen.
• Dokumentieren Sie die API gründlich.

REST vs. SOAP

• REST:
  • Architektonischer Stil.
  • Verwendet Standard-HTTP-Methoden.
  • Verwendet typischerweise JSON oder XML.
  • Einfach und leichtgewichtig.
• SOAP (Simple Object Access Protocol):
  • Protokoll.
  • Verwendet XML für das Nachrichtenformat.
  • Wird oft mit WS-* Standards für Sicherheit, Transaktionen usw. verwendet.
  • Komplexer und schwergewichtiger.

GraphQL vs. REST

• REST:
  • Mehrere Endpunkte.
  • Der Server bestimmt die zurückgegebenen Daten.
  • Kann zu Über- oder Unterabruf von Daten führen.
• GraphQL:
  • Einzelner Endpunkt.
  • Der Client gibt die benötigten Daten an.
  • Effizienterer Datenabruf.
• GraphQL wird oft für komplexe Anwendungen mit spezifischen Datenanforderungen bevorzugt.