Die sechs Architekturprinzipien
Damit eine API wirklich RESTful ist, muss sie eine Reihe von Constraints erfüllen. Roy Fielding beschreibt in Kapitel 5 seiner Dissertation sechs davon, und jeder wirkt sich konkret auf Skalierbarkeit, Wartbarkeit und Betrieb aus:
- Client-Server-Trennung: Frontend und Backend sind entkoppelt und entwickeln sich unabhängig weiter. Dein Web-Frontend, deine iOS-App und das Partnerportal nutzen dieselbe API, ohne dass das Backend wissen muss, wer fragt.
- Zustandslosigkeit (Stateless): Jede Anfrage enthält alle Informationen, die der Server zur Bearbeitung braucht. Der Server speichert zwischen zwei Requests keinen Sitzungszustand. Das ist der Schlüssel zur horizontalen Skalierung: Du kannst beliebig viele Server-Instanzen hinter einen Load Balancer hängen, weil keine Instanz wissen muss, was vorher passiert ist. Genau das brauchst du, wenn dein Shop am Black Friday ein Vielfaches der üblichen Last abfangen muss.
- Cachebarkeit: Antworten kennzeichnen über Header wie
Cache-Control und ETag, ob und wie lange sie zwischengespeichert werden dürfen. Gutes Caching entlastet die Datenbank und liefert häufig abgefragte Daten wie Produktkataloge und Kategorien schnell aus.
- Einheitliche Schnittstelle (Uniform Interface): laut Fielding das zentrale Merkmal, das REST von anderen Architekturstilen unterscheidet. Dazu gehören vier Regeln: Ressourcen werden über URIs identifiziert und über Repräsentationen wie JSON bearbeitet, Nachrichten beschreiben sich selbst, und Links in den Antworten steuern den weiteren Ablauf (Hypermedia as the Engine of Application State, kurz HATEOAS).
- Mehrschichtigkeit (Layered System): Zwischen Client und Server dürfen Proxies, Gateways oder Caches liegen, ohne dass der Client das merkt. Genau hier setzt ein API-Gateway an.
- Code on Demand (optional): Der Server darf ausführbaren Code an den Client schicken, etwa JavaScript. Das ist der einzige optionale Constraint.
In der Realität erfüllen viele „REST-APIs“ nicht alle sechs Constraints strikt. Im Alltag gilt ein pragmatisches „RESTful genug“. Das ist in Ordnung, solange du die Trade-offs bewusst triffst. Wer etwa auf Cachebarkeit verzichtet, sollte dafür einen guten Grund haben.
REST-API oder RESTful API? Das Richardson Maturity Model
Im Alltag werden „REST-API“ und „RESTful API“ gleichbedeutend verwendet. Wie RESTful eine Schnittstelle tatsächlich ist, lässt sich mit dem Reifegradmodell von Leonard Richardson einordnen, das Martin Fowler 2010 beschrieben hat:
- Level 0: HTTP dient nur als Transportweg. Alle Aufrufe gehen an einen einzigen Endpunkt, wie bei klassischem RPC.
- Level 1: Es gibt einzelne Ressourcen mit eigenen URLs, die Aktionen laufen aber meist weiter über eine einzige HTTP-Methode.
- Level 2: Methoden und Status-Codes werden so genutzt, wie HTTP sie vorsieht: GET liest, POST legt an, 404 meldet eine fehlende Ressource.
- Level 3: Hypermedia-Kontrollen (HATEOAS): Antworten enthalten Links auf die nächsten möglichen Aktionen, etwa von einer Bestellung zu ihrer Stornierung.
Fielding selbst ist hier streng: Für ihn ist eine API, deren Ablauf nicht über Hypertext gesteuert wird, keine REST-API. Fowler fasst zusammen, dass Level 3 für Fielding Voraussetzung für REST ist. Wer in Antworten keine Links auf Folgeaktionen liefert, bleibt nach dieser Lesart bei Level 2. Für die Praxis zählt vor allem, dass URLs, Methoden und Status-Codes konsistent sind.
HTTP-Status-Codes richtig nutzen
Eine gute REST-API meldet das Ergebnis über den HTTP-Status-Code und nicht über ein selbstgebautes Feld im Response-Body. Monitoring-Tools, Load Balancer, Caches und Client-Bibliotheken werten den Status-Code automatisch aus. Wer ihn ignoriert, verschenkt einen Großteil der Infrastruktur, die das Web ohnehin mitbringt. Die wichtigsten Gruppen:
Wer einen fehlgeschlagenen Login mit 200 OK und {"error": true} beantwortet, bricht mit dem Uniform-Interface-Prinzip und macht es Clients, Monitoring und Caches unnötig schwer. Genauso wichtig: 429 Too Many Requests signalisiert Rate-Limiting sauber, sodass ein gut gebauter Client mit Backoff reagiert und den Server nicht weiter flutet.
REST-API-Beispiel 1: die Shopware Store API
Shopware 6 bringt zwei HTTP-APIs mit, die mit Ressourcen-URLs und JSON arbeiten. Die Admin API unter /api ist für Backend-Integrationen, Importe und Datenabgleich gedacht und authentifiziert per OAuth 2.0 mit den Zugangsdaten einer Integration. Die Store API unter /store-api bedient Kunden-Frontends wie Headless-Storefronts und Apps. Sie erwartet den Zugriffsschlüssel eines Verkaufskanals im Header sw-access-key (Shopware-Dokumentation).
Ein typischer Lesezugriff holt Produkte. Suchparameter wie limit, filter oder sort stehen als JSON im Request-Body, includes legt fest, welche Felder zurückkommen:
POST /store-api/product HTTP/1.1
Host: shop.example.de
sw-access-key: SWSCXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json
Accept: application/json
{
"limit": 2,
"includes": {
"product": ["id", "productNumber", "name", "calculatedPrice"],
"calculated_price": ["unitPrice", "totalPrice"]
}
}
Die Antwort, gekürzt und mit Beispieldaten:
HTTP/1.1 200 OK
Content-Type: application/json
{
"elements": [
{
"id": "0192a4c1e5f87d3b9a6e2f4c8d1b7e30",
"productNumber": "SW-4711",
"name": "Arbeitshandschuh Profi",
"calculatedPrice": { "unitPrice": 12.9, "totalPrice": 12.9 },
"apiAlias": "product"
},
{
"id": "0192a4c1e5f87d3b9a6e2f4c8d1b7e31",
"productNumber": "SW-4712",
"name": "Schutzbrille Klar",
"calculatedPrice": { "unitPrice": 8.5, "totalPrice": 8.5 },
"apiAlias": "product"
}
],
"page": 1,
"limit": 2,
"total": 2,
"apiAlias": "dal_entity_search_result"
}
Daran lassen sich drei Dinge ablesen. Erstens steckt die Ressource in der URL (/store-api/product), der Zugriffsschlüssel im Header. Zweitens begrenzt includes die Antwort auf die Felder, die das Frontend wirklich braucht, und nimmt REST damit einen Teil des Over-Fetchings. Drittens kommen Fehler als Status-Code: Ohne sw-access-key antwortet die Store API mit 401 Unauthorized, ein unbekanntes Sortierfeld liefert 400 Bad Request mit dem Fehlercode FRAMEWORK__UNMAPPED_FIELD.
Ein Detail, das in Integrationen oft überrascht: Bei /store-api/product ermittelt Shopware ohne den Parameter total-count-mode keine Gesamtzahl der Treffer, total zählt dann nur die gelieferten Einträge. Für eine Paginierung mit Seitenzahlen setzt du dort "total-count-mode": 1. Das Produktlisting einer Kategorie (/store-api/product-listing/{categoryId}) liefert die Gesamtzahl von sich aus. Wie Warenkorb, Kundenkontext und Checkout über die Store API laufen, erklärt der Glossareintrag zur Store API.
Lesen per POST? Suchkriterien und HTTP-Caching
Dass ein Lesezugriff per POST läuft, wirkt auf den ersten Blick wie ein Verstoß gegen REST. Shopware begründet es mit den Suchkriterien: Filter, Sortierungen und Aggregationen werden schnell zu groß für eine URL. Der Preis dafür ist das Caching. Antworten auf POST sind nach RFC 9110 nur unter engen Bedingungen cachebar, und Shopware kennzeichnet nicht cachebare Store-API-Antworten mit Cache-Control: no-cache, private.
Mit Version 6.7.6 (Januar 2026) hat Shopware für lesende Routen wie Produktdetail, Produktlisting, Suche und Suchvorschläge GET-Varianten mit HTTP-Caching ergänzt (Release Notes). Komplexe Kriterien wandern dabei als komprimierter Query-Parameter _criteria in die URL. Shopware nennt das ausdrücklich eine Übergangslösung, bis die HTTP-Methode QUERY standardisiert ist. Die konfigurierbaren Caching-Policies sind laut Release Notes noch experimentell und hängen am Feature-Flag CACHE_REWORK.
Die Leitlinie aus der zugehörigen Architekturentscheidung lautet sinngemäß: GET für alles, was nichts verändert und keine sensiblen Daten liefert. Das ist auch für deine eigene REST-API eine gute Faustregel.
Bei Shop-Integrationen arbeiten oft beide APIs zusammen: Das ERP schreibt Bestände und Preise über die Admin API, das Frontend liest sie über die Store API. Dazwischen müssen Authentifizierung, Fehlerfälle und Wiederholungen sauber gelöst sein. Wie solche Anbindungen aussehen, zeigen die Seiten zu Shopware-Schnittstellen und zur API-Integration mit Drittanbietern.
REST-API-Beispiel 2: ein Controller in NestJS
Wie sieht die Serverseite einer REST-API aus? NestJS ist ein Framework für serverseitige Node.js-Anwendungen, gebaut mit TypeScript. Ressourcen, Methoden und Validierung drückt es über Decorators aus. Das folgende Beispiel bildet eine Bestell-Ressource ab. Zuerst die Datenobjekte (DTOs), die festlegen, was ein Client senden darf:
// Datei: order.dto.ts
import {
IsDateString,
IsInt,
IsOptional,
IsString,
Min,
} from 'class-validator';
export class CreateOrderDto {
@IsString()
customerNumber!: string;
@IsString()
sku!: string;
@IsInt()
@Min(1)
quantity!: number;
}
export class UpdateOrderDto {
@IsOptional()
@IsDateString()
deliveryDate?: string;
}
Dann der Controller. Jede Methode entspricht einer Kombination aus HTTP-Methode und Pfad:
// Datei: orders.controller.ts
import {
Body,
Controller,
DefaultValuePipe,
Delete,
Get,
HttpCode,
NotFoundException,
Param,
ParseIntPipe,
ParseUUIDPipe,
Patch,
Post,
Query,
} from '@nestjs/common';
import { CreateOrderDto, UpdateOrderDto } from './order.dto';
import { OrdersService } from './orders.service';
@Controller('v1/orders') // Ressource im Plural, Version im Pfad
export class OrdersController {
constructor(private readonly orders: OrdersService) {}
// GET /v1/orders?page=1&limit=20 → 200
@Get()
findAll(
@Query('page', new DefaultValuePipe(1), ParseIntPipe)
page: number,
@Query('limit', new DefaultValuePipe(20), ParseIntPipe)
limit: number,
) {
return this.orders.findAll(page, Math.min(limit, 100));
}
// GET /v1/orders/:id → 200, 404 oder 400 bei ungültiger ID
@Get(':id')
async findOne(@Param('id', ParseUUIDPipe) id: string) {
const order = await this.orders.findOne(id);
if (!order) throw new NotFoundException(`Bestellung ${id} fehlt`);
return order;
}
// POST /v1/orders → 201 Created (Nest-Standard für POST)
@Post()
create(@Body() dto: CreateOrderDto) {
return this.orders.create(dto);
}
// PATCH /v1/orders/:id → 200, ändert nur die gesendeten Felder
@Patch(':id')
async update(
@Param('id', ParseUUIDPipe) id: string,
@Body() dto: UpdateOrderDto,
) {
const order = await this.orders.update(id, dto);
if (!order) throw new NotFoundException(`Bestellung ${id} fehlt`);
return order;
}
// DELETE /v1/orders/:id → 204 No Content
@Delete(':id')
@HttpCode(204)
async remove(@Param('id', ParseUUIDPipe) id: string) {
await this.orders.remove(id);
}
}
Damit die Decorators an den DTOs greifen, schaltest du in main.ts die ValidationPipe global ein. Das Projekt braucht dafür die Pakete class-validator und class-transformer:
app.useGlobalPipes(
new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }),
);
whitelist entfernt Felder, die im DTO nicht deklariert sind. Mit forbidNonWhitelisted lehnt die API solche Anfragen stattdessen mit 400 ab (NestJS-Dokumentation). So kann ein Client zum Beispiel keinen Preis mitschicken, den das Backend gar nicht annehmen soll. Die Datenbanklogik steckt im OrdersService, der hier nicht abgedruckt ist.
Zwei Designentscheidungen stecken in diesem Beispiel. Die Liste begrenzt limit auf 100, damit kein Client mit einem einzigen Aufruf die ganze Tabelle zieht. Und ein zweites DELETE liefert wieder 204, weil der Zielzustand „Bestellung existiert nicht“ schon erreicht ist. Ebenso vertretbar wäre 404, denn RFC 9110 definiert Idempotenz über die beabsichtigte Wirkung auf dem Server. Wichtig ist, dass deine API sich dokumentiert und konsistent verhält.
Bewusst weggelassen sind Authentifizierung und Berechtigungen. In einem echten Projekt prüft ein Guard, ob der anfragende Kunde die Bestellung überhaupt sehen darf. Fehlt diese Prüfung, kann jeder mit einer gültigen ID fremde Bestellungen abrufen, ein klassischer Fall von Broken Access Control.
Aus denselben Decorators kann das Paket @nestjs/swagger eine OpenAPI-Spezifikation erzeugen (NestJS-Dokumentation zu OpenAPI). Damit die Felder der DTOs im Schema auftauchen, brauchen sie zusätzlich @ApiProperty() oder das Swagger-CLI-Plugin, das diese Angaben aus den Typen und den class-validator-Decorators ableitet. Dokumentation und Code bleiben so synchron, und das Frontend-Team kann daraus typisierte Clients generieren.
Weitere bekannte REST-APIs und OpenAPI
Die Stripe-API für Zahlungsabwicklung gilt als Paradebeispiel für sauberes REST-Design: klare Ressourcen wie /v1/customers oder /v1/payment_intents, konsistente Status-Codes, ein durchdachtes Pagination-Modell und eine sehr gute Dokumentation. Auch die GitHub REST API ist eine weit verbreitete, gut dokumentierte Schnittstelle, an der du dich beim eigenen Design orientieren kannst.
Zur formalen Beschreibung einer REST-API hat sich die OpenAPI-Spezifikation (früher Swagger) durchgesetzt. Sie beschreibt Endpunkte, Parameter und Datenmodelle maschinenlesbar in einer YAML- oder JSON-Datei. Daraus lassen sich Dokumentation, Client-SDKs in diversen Sprachen und Test-Stubs automatisch erzeugen. Du spezifizierst deine Schnittstelle einmal sauber und sparst danach an vielen Stellen Handarbeit. In unseren Enterprise-Projekten ist die OpenAPI-Spezifikation deshalb häufig der zentrale Vertrag zwischen Backend- und Frontend-Team.
Versionierung und Abwärtskompatibilität
Eine produktive API lebt jahrelang und wird von Systemen genutzt, die du nicht alle gleichzeitig aktualisieren kannst. Deshalb gehört ein Versionierungskonzept von Anfang an dazu. Üblich ist die Version im Pfad (/v1/, /v2/, wie im NestJS-Beispiel) oder im Header. Die goldene Regel: Bestehende Felder nie stillschweigend umdeuten oder entfernen. Neue Felder hinzuzufügen ist fast immer abwärtskompatibel, Entfernen oder Umbenennen nie. Wer das missachtet, legt Partner-Integrationen ohne Vorwarnung lahm.
REST vs. GraphQL: wann welcher Stil passt
REST ist die richtige Wahl, wenn deine Schnittstelle klar ressourcenorientiert ist, du breite Interoperabilität und gutes Caching brauchst und viele unterschiedliche Clients bedienst: Web, Mobile und Drittsysteme. An Grenzen stößt REST, wenn Clients sehr unterschiedliche, tief verschachtelte Daten brauchen. Dann führen Over-Fetching (zu viele Daten pro Antwort) und Under-Fetching (mehrere Roundtrips für eine Ansicht) zu Ineffizienz, besonders auf mobilen Verbindungen. Für solche Fälle ist GraphQL oft die bessere Alternative.
Die Angaben zu GraphQL folgen den Empfehlungen von graphql.org zum Betrieb über HTTP. Dass die Wahl auch Plattformanbieter beschäftigt, zeigt Shopify: Die REST Admin API ist dort seit dem 1. Oktober 2024 eine Legacy-API, neue öffentliche Apps müssen seit dem 1. April 2025 ausschließlich die GraphQL Admin API nutzen (Shopify-Dokumentation). Shopware hat seine Store API dagegen mit GET-Routen und HTTP-Caching ausgebaut.
In Microservices-Landschaften wird REST häufig für synchrone Service-zu-Service-Kommunikation eingesetzt, ergänzt durch ereignisgetriebene Muster wie Webhooks für asynchrone Benachrichtigungen. In der Praxis lautet die Frage selten „REST oder etwas anderes?“, sondern „welcher Stil für welchen Anwendungsfall?“. Eine ausführlichere Entscheidungshilfe zu REST, GraphQL und gRPC findest du im Beitrag zur Enterprise-Backend-Architektur.
Eine kompakte englische Zusammenfassung der REST-Grundbegriffe bietet das Glossar der MDN Web Docs.
Authentifizierung und Absicherung
Sobald deine REST-API mehr tut, als öffentliche Daten auszuliefern, brauchst du ein Konzept für Authentifizierung und Autorisierung. Verbreitet sind API-Keys für Server-zu-Server-Kommunikation, OAuth 2.0 mit Bearer-Tokens für Drittanbieter-Zugriffe und JSON Web Tokens (JWT). JWTs passen zur zustandslosen Natur von REST, weil sie die nötigen Claims selbst transportieren.
Bei Shopware verlangt die Admin API OAuth 2.0. Der sw-access-key der Store API ordnet eine Anfrage dagegen nur einem Verkaufskanal zu und ist kein Login: Laut Shopware ist die Store API öffentlich zugänglich, eine Anmeldung braucht es erst für kundenbezogene Endpunkte.
Eine produktive API gehört ausschließlich hinter TLS (HTTPS), ergänzt um Rate-Limiting, Eingabevalidierung wie im NestJS-Beispiel und ein durchdachtes Berechtigungsmodell. Gerade im B2B-Umfeld transportieren Schnittstellen oft sensible Bestell-, Preis- oder Kundendaten. Sicherheit gehört deshalb von Tag eins ins Design. Wer sie verschiebt, baut sich ein teures Nachrüstprojekt. Welche Risiken in solchen Stacks konkret auftreten, zeigt der Beitrag zu den OWASP Top 10 für Shopware- und NestJS-Projekte.
Häufige Fragen zu REST-APIs
Was bedeutet REST ausgeschrieben?
REST steht für Representational State Transfer und beschreibt einen Architekturstil für verteilte Systeme, den Roy Fielding im Jahr 2000 in seiner Dissertation definiert hat.
Was ist der Unterschied zwischen einer REST-API und einer RESTful API?
Im Alltag keiner, beide Begriffe meinen dasselbe. Streng genommen ist eine API nur dann RESTful, wenn sie alle REST-Constraints erfüllt, einschließlich der Hypermedia-Steuerung (Level 3 im Richardson Maturity Model). Viele APIs, die sich so nennen, verzichten auf diesen Teil.
Was ist ein Beispiel für eine REST-API?
Die Store API von Shopware: Ein POST auf /store-api/product mit dem Header sw-access-key liefert Produkte als JSON. Weitere bekannte Beispiele sind die APIs von Stripe und GitHub. Wie die Serverseite aussieht, zeigt der NestJS-Controller weiter oben.
Ist die Shopware-API eine REST-API?
Shopware selbst spricht von HTTP-basierten APIs mit JSON. Beide arbeiten mit Ressourcen-URLs, HTTP-Methoden und Status-Codes und werden deshalb im Alltag als REST-APIs bezeichnet: die Admin API für Integrationen, die Store API für Frontends und Apps. Eine Besonderheit: Viele lesende Store-API-Routen nehmen Suchkriterien per POST entgegen. Seit Version 6.7.6 gibt es für zentrale Leserouten zusätzlich GET mit HTTP-Caching.
Ist REST dasselbe wie HTTP?
Nein. HTTP ist das Transportprotokoll, das REST in der Praxis fast immer nutzt. REST selbst ist ein Architekturstil, der theoretisch auch mit anderen Protokollen funktionieren könnte, in der Realität aber praktisch immer auf HTTP aufsetzt.
Was ist der Unterschied zwischen REST und SOAP?
SOAP ist ein striktes, XML-basiertes Protokoll mit festem Nachrichtenformat und eigenem Standard-Stack. REST ist leichtgewichtiger, nutzt meist JSON und setzt auf die nativen HTTP-Mechanismen. REST ist heute im Web deutlich verbreiteter, SOAP findet sich noch in älteren Enterprise- und Behörden-Schnittstellen.
Was heißt zustandslos bei REST?
Der Server speichert zwischen zwei Anfragen keinen Sitzungszustand. Jede Anfrage muss alle nötigen Informationen mitbringen, etwa ein Auth-Token. Das ermöglicht horizontale Skalierung über viele Server-Instanzen.
Brauche ich für eine REST-API zwingend JSON?
Nein, aber JSON ist das übliche Format. REST ist formatunabhängig: Über den Accept-Header kann ein Client auch XML oder andere Repräsentationen anfordern (Content Negotiation).
