RESTful API: Prinzipien, Design und bewährte Methoden

RESTful API (Representational State Transfer API) ist ein Netzwerk-Interface-Designstil, der für Interaktionen zwischen Netzwerkanwendungen verwendet wird. REST ist eher eine Reihe von Architekturprinzipien und -beschränkungen als ein Standard oder ein Protokoll. Wenn ein Webdienst "RESTful" ist, befolgt er die REST-Prinzipien und bietet einen effizienten, zuverlässigen und skalierbaren Netzwerkdienst.

In einem RESTful-Dienst sollte jede Anfrage alle notwendigen Informationen enthalten, um die Anfrage zu verarbeiten. Der Server sollte keine Zustandsinformationen über Client-Anfragen speichern.

Eine RESTful-Architektur kann aus mehreren Schichten bestehen, von denen jede eine bestimmte Funktion erfüllt. Diese Struktur ermöglicht die Entwicklung komplexerer und leistungsfähigerer Anwendungen.

URI Design

Beim RESTful-API-Design repräsentieren URLs (Uniform Resource Locators) typischerweise Ressourcen (Objekte), während HTTP-Methoden (wie GET, POST, PUT, DELETE usw.) Operationen an diesen Ressourcen (Verben) darstellen. Dieser Designstil betont den Zustand und die Repräsentation von Ressourcen anstatt Aktionen.

Verb + Object

Verben in RESTful APIs sind üblicherweise die fünf HTTP-Methoden, die CRUD-Operationen entsprechen:

• GET: Lesen
• POST: Erstellen
• PUT: Aktualisieren
• PATCH: Aktualisieren (typischerweise für partielle Aktualisierungen)
• DELETE: Löschen

Gemäß der HTTP-Spezifikation sollten Verben immer in Großbuchstaben stehen.

Das Objekt Muss ein Substantiv Sein

Beim Entwerfen einer API repräsentiert die URL (Uniform Resource Locator) normalerweise eine Ressource, die als das Objekt eines HTTP-Verbs dient. Gemäß den RESTful-Designprinzipien sollten URLs Substantive anstelle von Verben sein, da sie eine "Ressourcen"-Sammlung oder eine einzelne Instanz darstellen, nicht eine Aktion.

Falsche Beispiele:

• /getAllCars
• /createNewCar
• /deleteAllRedCars

Diese URLs enthalten Verben (wie get, create, delete), die Aktionen anstelle der Ressourcen selbst beschreiben. Dieses Design entspricht nicht den semantischen RESTful-Standards.

Korrekte Vorgehensweise:

URLs sollten sich auf die Beschreibung von Ressourcen anstatt auf Operationen konzentrieren. Nachfolgend sind Beispiele für konforme URL-Designs:

• /users: Repräsentiert eine Sammlung von Benutzern
• /users/123: Repräsentiert einen einzelnen Benutzer mit einer spezifischen ID (123)

In den obigen Beispielen sind /users und /users/123 beides Substantive, die eine Sammlung von Benutzern bzw. eine bestimmte Benutzerressource darstellen. Ein solches URL-Design macht APIs leichter verständlich und stimmt mit den RESTful-Ressourcenorientierungsprinzipien überein.

Durch die Befolgung dieser Namenskonvention stellen wir sicher, dass API-Pfade klar, konsistent, leicht verständlich und wartbar sind.

Plurale URLs

Die Verwendung der Pluralform in URLs wird im Allgemeinen aus Gründen der Konsistenz und Klarheit empfohlen, da diese typischerweise Sammlungen von Ressourcen darstellen.

Wenn Ihre URL auf eine Sammlung von Ressourcen verweist, verwenden Sie Plural-Substantive. Verwenden Sie beispielsweise /users anstelle von /user, um eine Sammlung aller Benutzer darzustellen.

Auch wenn Sie auf eine einzelne Ressource verweisen, wird die Verwendung der Pluralform empfohlen. Zum Beispiel repräsentiert /users/123 den Benutzer mit der ID 123. Dieser Ansatz sorgt für URL-Konsistenz.

Wenn Ressourcen hierarchische Beziehungen haben, sollte die URL diese Struktur widerspiegeln. Zum Beispiel kann /users/123/posts die Sammlung von Beiträgen für den Benutzer 123 darstellen.

Vermeiden Sie Tief Verschachtelte URLs

Ein häufiges Szenario ist, wenn Ressourcen mehrere Klassifizierungsebenen erfordern, was zu tief verschachtelten URLs führt, wie beispielsweise das Abrufen einer bestimmten Kategorie von Artikeln durch einen bestimmten Autor:

GET /authors/12/categories/2

Solche URLs sind schwer zu erweitern und ihre Semantik ist unklar, was oft zusätzlichen Aufwand erfordert, um sie zu verstehen. Ein besserer Ansatz ist die Verwendung von Abfrageparametern jenseits der ersten Ebene:

GET /authors/12?categories=2

Ein weiteres Beispiel ist das Abfragen veröffentlichter Artikel. Sie könnten die URL wie folgt gestalten:

GET /articles/published

Die Verwendung von Abfrageparametern ist jedoch eindeutig ein besserer Ansatz:

GET /articles?published=true

Status Codes

Status Codes Müssen Präzise Sein

Für jede Client-Anfrage muss der Server mit einem HTTP-Statuscode und Daten antworten.

Ein HTTP-Statuscode ist eine dreistellige Zahl, die in fünf Kategorien unterteilt ist:

• 1xx: Informationell
• 2xx: Erfolg
• 3xx: Weiterleitung
• 4xx: Client-Fehler
• 5xx: Server-Fehler

Diese fünf Kategorien enthalten über 100 Statuscodes, die die meisten möglichen Situationen abdecken. Jeder Statuscode hat eine Standardbedeutung (oder eine konventionell akzeptierte Bedeutung), die es dem Client ermöglicht, allein durch Überprüfen des Statuscodes zu bestimmen, was passiert ist. Daher sollte der Server den präzisesten möglichen Statuscode zurückgeben.

APIs benötigen keine 1xx-Statuscodes. Nachfolgend eine Erläuterung der anderen vier Kategorien.

2xx Status Codes

Verschiedene HTTP-Anforderungsmethoden sollten entsprechende Statuscodes zurückgeben, um das Anforderungsergebnis anzuzeigen. Während 200 OK eine allgemeine Erfolgsantwort ist, sollten je nach Methode präzisere Statuscodes verwendet werden:

• GET: 200 OK – Die Anforderung war erfolgreich und die Ressource wird zurückgegeben.
• POST: 201 Created – Eine neue Ressource wurde erfolgreich erstellt und die Antwort enthält typischerweise den URI der Ressource.
• PUT: 200 OK oder 204 No Content – Wird für vollständige Ressourcenaktualisierungen verwendet. Wenn Inhalt zurückgegeben wird, verwenden Sie 200; wenn nicht, verwenden Sie 204.
• PATCH: 200 OK oder 204 No Content – Wird für partielle Aktualisierungen verwendet, ähnlich wie PUT. 204 zeigt an, dass kein Inhalt zurückgegeben wird.
• DELETE: 204 No Content – Zeigt an, dass die Ressource erfolgreich gelöscht wurde, normalerweise ohne Inhalt in der Antwort.
• 202 Accepted – Die Anforderung wurde akzeptiert, aber noch nicht verarbeitet, nützlich für asynchrone Operationen.
• 206 Partial Content – Zeigt eine partielle Antwort an, die üblicherweise verwendet wird, wenn ein Client einen Teil einer großen Datei mithilfe des Range-Headers anfordert.

3xx Status Codes

APIs verwenden typischerweise nicht 301 (Permanent Redirect) oder 302 (Temporary Redirect, einschließlich 307), da diese hauptsächlich für die Navigation auf Browserebene relevant sind. APIs können solche Szenarien stattdessen auf Anwendungsebene behandeln.

Allerdings können APIs 303 See Other verwenden, was auf eine andere URL verweist. Wie 302 und 307 bedeutet dies "temporäre Weiterleitung", aber 303 wird speziell für POST-, PUT- und DELETE-Anfragen verwendet. Im Gegensatz zu 302 folgen Browser einer 303-Weiterleitung nicht automatisch, sondern überlassen dem Benutzer die Entscheidung über den nächsten Schritt.

Beispiel einer Antwort:

HTTP/1.1 303 See Other
Location: /api/orders/12345

4xx Status Codes

4xx-Statuscodes weisen auf Client-Fehler hin. Häufige sind:

• 400 Bad Request – Der Server versteht die Anforderung des Clients nicht und verarbeitet sie nicht.
• 401 Unauthorized – Der Benutzer hat keine Authentifizierungsdaten angegeben oder die Authentifizierung ist fehlgeschlagen.
• 403 Forbidden – Der Benutzer hat sich erfolgreich authentifiziert, hat aber keine Berechtigung, auf die Ressource zuzugreifen.
• 404 Not Found – Die angeforderte Ressource existiert nicht oder ist nicht verfügbar.
• 405 Method Not Allowed – Der Benutzer hat sich erfolgreich authentifiziert, verwendet aber eine HTTP-Methode, die nicht zulässig ist.
• 410 Gone – Die angeforderte Ressource wurde dauerhaft entfernt.
• 415 Unsupported Media Type – Das angeforderte Format wird nicht unterstützt. Wenn die API beispielsweise nur JSON zurückgibt, der Client aber XML anfordert, sollte dieser Status zurückgegeben werden.
• 422 Unprocessable Entity – Der Client hat einen Anhang bereitgestellt, der nicht verarbeitet werden konnte, was zu einer fehlgeschlagenen Anforderung führte.
• 429 Too Many Requests – Der Client hat die zulässige Anzahl von Anforderungen überschritten.

5xx Status Codes

5xx-Statuscodes weisen auf Server-Fehler hin. APIs legen interne Serverdetails im Allgemeinen nicht für Benutzer offen, daher werden nur zwei Statuscodes häufig verwendet:

• 500 Internal Server Error – Die Client-Anforderung war gültig, aber der Server ist bei der Verarbeitung auf ein unerwartetes Problem gestoßen.
• 503 Service Unavailable – Der Server ist vorübergehend nicht in der Lage, Anfragen zu verarbeiten, was häufig während Wartungsarbeiten verwendet wird.

Server Antworten

Geben Sie Keinen Reinen Text Zurück

API-Antworten sollten kein reiner Text, sondern strukturierte JSON-Objekte sein, um ein Standardformat zu gewährleisten. Der Content-Type-Header des Servers sollte auf application/json gesetzt sein.

Der Client sollte auch angeben, dass er JSON-Antworten akzeptiert, indem er den Accept-Header in seiner Anforderung setzt:

GET /orders/2 HTTP/1.1
Accept: application/json

Geben Sie Keinen 200 Status Code Für Fehler Zurück

Ein falscher Ansatz ist es, immer 200 OK zurückzugeben, selbst wenn ein Fehler auftritt, und die Fehlerdetails im Antworttext anzugeben. Dies zwingt den Client, den Antworttext zu parsen, um festzustellen, ob die Anforderung fehlgeschlagen ist, was den Zweck von Statuscodes untergräbt.

Schlechtes Beispiel:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

In diesem Fall ist die Anforderung fehlgeschlagen, aber der Server hat trotzdem 200 OK zurückgegeben. Der Client muss das Feld "status": "failure" im Antworttext überprüfen, um den Fehler zu erkennen. Dieser Ansatz ist nicht RESTful und macht die Fehlerbehandlung komplexer und fehleranfälliger.

Korrektes Beispiel:

Der Statuscode sollte das Ergebnis der Anforderung angeben. Fehler sollten mithilfe der entsprechenden Statuscodes übermittelt werden, während der Antworttext weitere Details liefert.

Wenn die Anforderung beispielsweise ungültig ist, sollte der Server 400 Bad Request zurückgeben, wobei Fehlerdetails im JSON-Format vorliegen:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Invalid payload.",
  "detail": {
    "surname": "This field is required."
  }
}

Hier zeigt 400 deutlich eine ungültige Anforderung an, während der Antworttext spezifische Fehlerdetails liefert, um dem Client zu helfen, das Problem zu verstehen.

Bereitstellung von Links

In RESTful APIs ist das Einfügen von Links in Antworten eine gängige Praxis. Dies folgt dem Prinzip Hypermedia as the Engine of Application State (HATEOAS), das die API-Auffindbarkeit und Selbsterklärung verbessert.

Hier sind zwei gängige Methoden, um Links einzufügen:

Verwenden von HAL (Hypertext Application Language)

HAL ist ein beliebtes Hypermedia-Format, das Beziehungen zwischen Ressourcen darstellt. Es verwendet das Feld _links in JSON-Antworten:

{
  "id": 1,
  "name": "Example",
  "_links": {
    "self": {
      "href": "http://api.example.com/resource/1"
    },
    "related": {
      "href": "http://api.example.com/resource/2"
    }
  }
}

Einbetten von Links Direkt in JSON

{
  "id": 1,
  "name": "Example",
  "links": {
    "self": "http://api.example.com/resource/1",
    "related": "http://api.example.com/resource/2"
  }
}

Content Return Policies

Im RESTful API-Design werden POST-Anfragen verwendet, um neue Ressourcen zu erstellen. Ob die Antwort die neu erstellte Ressource enthalten soll, hängt von den Implementierungsbedürfnissen ab. Es gibt zwei gängige Ansätze:

1. Rückgabe der Erstellten Ressource

Dieser Ansatz beinhaltet einen 201 Created-Statuscode und die vollständigen Details der neuen Ressource in der Antwort. Er enthält auch einen Location-Header, der auf den URI der Ressource verweist.

HTTP/1.1 201 Created
Location: /resources/123
Content-Type: application/json
{
  "id": 123,
  "name": "New Resource"
}

2. Kein Inhalt Zurückgeben

Alternativ kann der Server wählen, nur eine 201 Created- oder 204 No Content-Antwort mit einem Location-Header zurückzugeben, wobei Ressourcendetails weggelassen werden. Dies minimiert die Datenübertragung und ermöglicht es dem Client, zu entscheiden, ob er die Ressource später abrufen möchte.

HTTP/1.1 201 Created
Location: /resources/123

Fazit

RESTful APIs folgen dem HTTP-Protokoll und betonen die Ressourcendarstellung und zustandslose Interaktionen. Durch die Verwendung von Standard-HTTP-Methoden (GET, POST, PUT, DELETE) und präzisen Statuscodes bieten RESTful-Architekturen eine einfache, effiziente und leicht zu wartende Möglichkeit, Netzwerkanwendungen zu erstellen. Dieser Ansatz verbessert die Skalierbarkeit, Flexibilität und Wartbarkeit für Webdienste.

---

Wir sind Leapcell, Ihre erste Wahl für das Hosten von Backend-Projekten.

Leapcell ist die Serverlose Plattform der nächsten Generation für Webhosting, Async Tasks und Redis:

Multi-Language Support

• Entwickeln Sie mit Node.js, Python, Go oder Rust.

Unbegrenzte Projekte kostenlos bereitstellen

• Zahlen Sie nur für die Nutzung – keine Anfragen, keine Gebühren.

Unschlagbare Kosteneffizienz

• Pay-as-you-go ohne Leerlaufgebühren.
• Beispiel: 25 US-Dollar unterstützen 6,94 Millionen Anfragen bei einer durchschnittlichen Antwortzeit von 60 ms.

Optimierte Entwicklererfahrung

• Intuitive Benutzeroberfläche für mühelose Einrichtung.
• Vollautomatisierte CI/CD-Pipelines und GitOps-Integration.
• Echtzeitmetriken und -protokollierung für umsetzbare Erkenntnisse.

Mühelose Skalierbarkeit und Hohe Leistung

• Automatische Skalierung zur einfachen Bewältigung hoher Parallelität.
• Null Betriebsaufwand – konzentrieren Sie sich einfach auf das Erstellen.

Erfahren Sie mehr in der Dokumentation!

Folgen Sie uns auf X: @LeapcellHQ