Wer APIs entwickelt, kennt das Dilemma: Eine Ressource soll abgefragt werden, aber die Anfrage ist zu komplex für klassische URL-Parameter. Häufig landet man dann bei POST, obwohl eigentlich nichts verändert werden soll.
Genau hier setzt die neue HTTP-Methode QUERY an. Sie wurde 2026 mit RFC 10008 standardisiert und schliesst eine Lücke zwischen GET und POST.
Was ist HTTP QUERY?
QUERY ist eine HTTP-Methode für serverseitige Abfragen. Anders als bei GET kann die eigentliche Abfrage im Request Body übertragen werden:
QUERY /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"location": "Zurich",
"postalCodes": ["8001", "8002"],
"roles": ["admin", "editor"],
"active": true
}Der Server interpretiert den Body als Abfrage und liefert die passenden Benutzenden zurück.
Der entscheidende Punkt: QUERY ist «safe» und «idempotent». Die Anfrage verändert also keine Daten auf dem Server und kann wiederholt werden, ohne dass sich der Serverzustand dadurch verändert.
Warum braucht es QUERY?
Für einfache Abfragen bleibt GET die passende Wahl:
GET /users?location=Zurich&postalCode=8001 HTTP/1.1
Host: api.example.com
Bei komplexeren Filtern werden URLs jedoch schnell unübersichtlich:
/users?location=Zurich&postalCode=8001&postalCode=8002&role=admin&active=true&sort=-createdAt
Komplexe Suchlogik lässt sich zwar über URL-Parameter abbilden, aber URLs können je nach Browser, Proxy oder Server in ihrer Länge begrenzt sein. Zudem werden sie häufig geloggt oder gecacht.
Die bisherige Alternative ist häufig POST:
POST /users/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"location": "Zurich",
"postalCodes": ["8001", "8002"],
"roles": ["admin", "editor"],
"active": true
}
Technisch funktioniert das gut, semantisch ist es aber nicht ideal. POST wird typischerweise für Operationen verwendet, die beispielsweise Daten verändern oder neue Ressourcen erzeugen. Bei einer Suche wollen wir dagegen nur Daten abrufen.
QUERY macht diese Absicht explizit.
Warum nicht GET mit Body?
Warum kann GET nicht einfach einen Request Body für solche Abfragen verwenden? Das Problem: HTTP definiert für den Content eines GET-Requests keine allgemeine Semantik. Andere Komponenten der HTTP-Infrastruktur können daher nicht davon ausgehen, dass dieser Body eine bestimmte Bedeutung hat. Bei QUERY ist der Request Body dagegen Bestandteil der definierten Semantik der Methode. QUERY ist deshalb nicht einfach «GET mit Body», sondern eine eigene HTTP-Methode.
| Methode | Einsatz | Body | Safe | Idempotent |
|---|---|---|---|---|
| GET | Einfache Abfragen | Keine definierte Semantik | ✓ | ✓ |
| QUERY | Komplexe Abfragen | Erwartet | ✓ | ✓ |
| POST | Operationen / Änderungen | Erwartet | – | – |
Damit bleibt die klassische Aufteilung sinnvoll:
- GET: Einfache Abfrage / Ressource abrufen
- QUERY: Komplexe Abfrage mit Request Body
- POST: Operationen, die beispielsweise Daten verändern
Was bedeutet das für API-Design?
Der grösste Vorteil von QUERY ist nicht, dass damit Dinge möglich werden, die mit POST nicht möglich wären. Entscheidend ist die klare Semantik.
Eine API kann damit eindeutig ausdrücken:
- Die Anfrage verändert keine Daten.
- Die Anfrage ist wiederholbar.
- Die Abfrage wird im Request Body übermittelt.
- Es handelt sich um eine Abfrage und nicht um eine allgemeine Aktion.
Für komplexe Abfragen kann ausserdem «Content-Location» genutzt werden, um auf ein gespeichertes Ergebnis zu verweisen und dieses später erneut abzurufen.
Fazit
QUERY ergänzt GET und POST um eine Methode für komplexe Abfragen mit Request Body, ohne den Serverzustand zu verändern.
GET eignet sich weiterhin für einfache Abfragen, POST für Operationen und Änderungen. QUERY wird interessant, wenn eine Abfrage zu komplex für eine URL wird, aber trotzdem klar als reine, wiederholbare Abfrage gekennzeichnet werden soll.
Damit bietet QUERY eine neue Möglichkeit, komplexe Filter und Suchabfragen in APIs klar und eindeutig abzubilden.
