REST API Grundlagen

6 Kernkonzepte

Die wichtigsten REST-API-Konzepte für die Entwicklung von Web-APIs: Prinzipien · Ressourcen · HTTP-Methoden · Statuscodes · HATEOAS · Reifegradmodell REST (Representational State Transfer) ist ein Architekturstil für Web-APIs. Diese Cheatsheet fasst die grundlegenden Konzepte, Prinzipien und Best Practices für die Entwicklung von RESTful APIs zusammen.

REST-Prinzipien – Die 6 Grundsätze

Client-Server · Stateless · Cache · Uniform Interface · Layered · Code-on-Demand

# REST-Prinzipien Client-Server – Trennung von Frontend und Backend Stateless – Jede Anfrage enthält alle notwendigen Informationen Cache – Antworten sollten cachable sein Uniform Interface – Einheitliche Schnittstelle (URI, Methoden, Headers) Layered System – Schichtenarchitektur (Proxy, Load Balancer) Code-on-Demand (optional) – Auslieferung von ausführbarem Code

REST-Prinzipien definieren die grundlegenden Architekturregeln für RESTful APIs. Sie wurden von Roy Fielding in seiner Dissertation definiert.

Erklärung

# 1. Client-Server – Unabhängige Entwicklung von Frontend und Backend

# 2. Stateless – Keine Session auf dem Server; jeder Request ist unabhängig

# 3. Cache – Antworten können vom Client oder Proxy gecacht werden

# 4. Uniform Interface – Einheitliche Ressourcen-Identifikation (URI) und Manipulation (HTTP-Methoden)

# 5. Layered System – API kann über mehrere Schichten (z.B. Load Balancer, Proxy) laufen

# 6. Code-on-Demand (optional) – Server kann Client Code ausliefern (z.B. JavaScript)

# Wichtigstes Prinzip: Uniform Interface + Stateless = Skalierbarkeit

Tipp: Die wichtigsten Prinzipien für die Praxis sind Stateless (keine Serversessions) und Uniform Interface (konsistente Nutzung von URIs, HTTP-Methoden und Statuscodes). Diese beiden Prinzipien machen REST so skalierbar.

Ressourcen – URIs & Repräsentationen

/users · /users/42 · /orders · /products

# Ressourcen-URI-Struktur GET /users # Alle Benutzer GET /users/42 # Benutzer mit ID 42 GET /users/42/orders # Bestellungen von Benutzer 42 GET /products?category=books # Gefilterte Ressourcen

Ressourcen sind die zentralen Elemente einer REST-API. Jede Ressource wird durch eine URI (Uniform Resource Identifier) identifiziert und kann verschiedene Repräsentationen (JSON, XML, etc.) haben.

Ressourcen-Namenskonventionen

Konvention	Beschreibung	Beispiel
Substantive (Plural)	Ressourcen als Substantive im Plural	/users, /products, /orders
Verschachtelung	Beziehungen zwischen Ressourcen	/users/42/orders
Filter/Parameter	Query-Parameter für Filter, Sortierung	/products?category=books&sort=price
HTTP-Methoden	Keine Verben in der URI!	❌ /getUsers, ✅ /users
Kleinbuchstaben	URIs in Kleinbuchstaben	/api/v1/users

Beispiele

# Ressourcen-URIs für eine Blog-API

GET /api/v1/posts # Alle Beiträge

GET /api/v1/posts/42 # Beitrag mit ID 42

GET /api/v1/posts/42/comments # Kommentare zu Beitrag 42

GET /api/v1/users/123/posts # Beiträge von User 123

# Versionierung – API-Version in der URI

/api/v1/ # Version 1

/api/v2/ # Version 2

Tipp: Verwenden Sie Substantive im Plural für Ressourcen-URIs – /users statt /user. Vermeiden Sie Verben in der URI – sie gehören in die HTTP-Methode (GET, POST, PUT, DELETE).

HTTP-Methoden – CRUD-Operationen

GET · POST · PUT · DELETE · PATCH · HEAD · OPTIONS

GET /users # Auflisten GET /users/42 # Einzelnes Element POST /users # Erstellen PUT /users/42 # Vollständig ersetzen PATCH /users/42 # Teilweise aktualisieren DELETE /users/42 # Löschen

HTTP-Methoden definieren die Aktion auf der Ressource. In RESTful APIs folgen sie dem CRUD-Prinzip (Create, Read, Update, Delete).

Methoden im REST-Kontext

Methode	CRUD	Idempotent	Safe	Beschreibung
GET	Read	✅	✅	Ressource abrufen
HEAD	Read	✅	✅	Nur Header abrufen
OPTIONS	—	✅	✅	Unterstützte Methoden abfragen
POST	Create	❌	❌	Neue Ressource erstellen
PUT	Update	✅	❌	Ressource vollständig ersetzen
PATCH	Update	❌	❌	Ressource teilweise aktualisieren
DELETE	Delete	✅	❌	Ressource löschen

Beispiele

# GET – Alle Benutzer abrufen

GET /api/users

# POST – Neuen Benutzer erstellen (mit Body)

POST /api/users

{ "name": "Anna", "email": "anna@example.com" }

# PUT – Benutzer vollständig aktualisieren (alle Felder)

PUT /api/users/42

{ "name": "Anna Schmidt", "email": "anna.schmidt@example.com" }

# PATCH – Benutzer teilweise aktualisieren (nur name)

PATCH /api/users/42

{ "name": "Anna Schmidt" }

# DELETE – Benutzer löschen

DELETE /api/users/42

Tipp: Verwenden Sie PUT für vollständige Updates (Client sendet das gesamte Objekt) und PATCH für Teil-Updates (nur die geänderten Felder). POST ist nicht idempotent – jede Anfrage erzeugt eine neue Ressource.

Statuscodes – Antworten kategorisieren

200 OK · 201 Created · 400 Bad Request · 401 Unauthorized · 404 Not Found

# 2xx – Erfolg 200 OK # Erfolgreiche GET/PUT/PATCH 201 Created # Ressource erstellt (POST) 204 No Content # Erfolg, kein Body (DELETE) # 4xx – Client-Fehler 400 Bad Request # Ungültige Anfrage 401 Unauthorized # Authentifizierung fehlt 403 Forbidden # Keine Berechtigung 404 Not Found # Ressource nicht gefunden 422 Unprocessable Entity # Validierungsfehler

Statuscodes geben das Ergebnis der Anfrage zurück. RESTful APIs verwenden die HTTP-Statuscodes konsistent, um Erfolg, Fehler und Weiterleitungen zu kommunizieren.

Wichtige Statuscodes für REST-APIs

Code	Name	Verwendung	Body
200	OK	GET, PUT, PATCH (Erfolg)	✅
201	Created	POST (Ressource erstellt)	✅ (oder Location)
202	Accepted	Asynchrone Operation	✅ (optional)
204	No Content	DELETE, erfolgreiche Operation ohne Body	❌
301	Moved Permanently	Dauerhafte Weiterleitung	❌
400	Bad Request	Ungültige Anfrage (Syntax, Validierung)	✅ (Fehlerdetails)
401	Unauthorized	Authentifizierung erforderlich	✅ (optional)
403	Forbidden	Keine Berechtigung	✅ (optional)
404	Not Found	Ressource nicht gefunden	✅ (optional)
405	Method Not Allowed	HTTP-Methode nicht erlaubt	✅ (optional)
409	Conflict	Konflikt (z.B. veraltete Version)	✅ (Fehlerdetails)
422	Unprocessable Entity	Validierungsfehler	✅ (Fehlerdetails)
429	Too Many Requests	Ratenlimit überschritten	✅ (optional)
500	Internal Server Error	Allgemeiner Server-Fehler	✅ (optional)

Beispiele

# 200 OK – Erfolgreicher GET

HTTP/1.1 200 OK

{ "id": 42, "name": "Anna" }

# 201 Created – Ressource erstellt

HTTP/1.1 201 Created

Location: /api/users/43

# 422 Unprocessable Entity – Validierungsfehler

HTTP/1.1 422 Unprocessable Entity

{ "errors": { "email": ["must be a valid email"] } }

Tipp: Bei POST sollte 201 Created mit dem Location-Header zurückgegeben werden. Bei DELETE ist 204 No Content die übliche Antwort. Bei Validierungsfehlern verwenden Sie 422 Unprocessable Entity mit aussagekräftigen Fehlermeldungen.

HATEOAS – Hypermedia as the Engine of Application State

_links · HAL · JSON-LD

# HATEOAS-Antwort mit HAL-Format { "_links": { "self": { "href": "/api/users/42" }, "orders": { "href": "/api/users/42/orders" }, "profile": { "href": "/api/users/42/profile" } }, "id": 42, "name": "Anna" }

HATEOAS ist ein Prinzip, bei dem die API-Antwort Links zu verwandten Ressourcen enthält. Der Client navigiert über diese Links, statt URIs selbst zu konstruieren. Erreicht wird dies durch Formate wie HAL oder JSON-LD.

Beispiele

# HAL (Hypertext Application Language) – JSON mit _links

{

"_links": {

"self": { "href": "/api/users" },

"next": { "href": "/api/users?page=2" },

"prev": { "href": "/api/users?page=1" },

"create": { "href": "/api/users", "method": "POST" }

"_embedded": {

"users": [

{ "id": 1, "name": "Anna", "_links": { "self": { "href": "/api/users/1" } } }

]

}

# Vorteile von HATEOAS:

# – Client muss keine URIs hardcoden

# – API-Änderungen können ohne Client-Anpassungen erfolgen

# – Selbstbeschreibende API (Entdeckbarkeit)

Tipp: HATEOAS ist das fortgeschrittenste REST-Prinzip und wird in der Praxis nicht immer umgesetzt. Für öffentliche APIs ist es jedoch ein starkes Alleinstellungsmerkmal. Beliebte Formate sind HAL (JSON) und JSON-LD.

Richardson Maturity Model – Reifegrad von REST-APIs

Level 0 · Level 1 · Level 2 · Level 3

# Level 0 – The Swamp of POX Ein einziger URI, eine Methode (z.B. POST), RPC-Stil # Level 1 – Resources Mehrere URIs für Ressourcen, aber nur eine Methode # Level 2 – HTTP Verbs Korrekte Verwendung von HTTP-Methoden und Statuscodes # Level 3 – Hypermedia Controls (HATEOAS) Links in Antworten zur Navigation

Richardson Maturity Model bewertet den Reifegrad einer REST-API in vier Stufen. Die meisten realen APIs erreichen Level 2 – die konsequente Nutzung von HTTP-Methoden und Statuscodes.

Die vier Level im Detail

Level	Name	Beschreibung	Beispiel
0	Swamp of POX	Ein einziger URI, nur POST, RPC-Stil	POST /api, Body: { method: "getUser", id: 42 }
1	Resources	Mehrere URIs für Ressourcen, aber nur eine Methode	POST /users/42 (zum Abrufen)
2	HTTP Verbs	Korrekte HTTP-Methoden (GET, POST, PUT, DELETE) und Statuscodes	GET /users/42 → 200 OK
3	Hypermedia Controls	HATEOAS – Links zu verwandten Ressourcen	GET /users/42 → _links: { orders: ... }

Level-Vergleich

# Level 0: RPC-Style (XML-RPC, SOAP-ähnlich)

POST /api

{ "method": "getUser", "params": { "id": 42 } }

# Level 1: Resources (aber nur POST)

POST /users/42

# Level 2: HTTP Verbs (RESTful)

GET /users/42 → 200 OK

PUT /users/42 → 200 OK

DELETE /users/42 → 204 No Content

# Level 3: Hypermedia (HATEOAS)

GET /users/42

{ "id": 42, "name": "Anna", "_links": { "self": "/users/42", "orders": "/users/42/orders" } }

Tipp: Die meisten APIs erreichen Level 2 – das ist der praktische Standard. Level 3 (HATEOAS) ist das Ideal für wirklich selbstbeschreibende APIs, wird aber oft aus Komplexitätsgründen nicht umgesetzt. Für öffentliche APIs ist Level 3 jedoch ein starkes Qualitätsmerkmal.

REST API Kernkonzepte im Überblick

REST Architekturstil
Stateless, Cache, Uniform Interface

Ressource URI + Repräsentation
/users, /products

CRUD Create, Read, Update, Delete
POST, GET, PUT/PATCH, DELETE

Statuscodes 2xx, 4xx, 5xx
200, 201, 400, 404, 500

HATEOAS Hypermedia Links
_links, HAL, JSON-LD

Maturity Level 0–3
RPC → RESTful → HATEOAS

Quick Summary

Stateless

Keine Sessions

URI

Ressourcen

GET

Methoden

200

Statuscodes

_links

HATEOAS

Level 2

Maturity Model

GET /users → 200 OK · POST /users → 201 Created · PUT /users/42 → 200 OK · DELETE /users/42 → 204 No Content