Die neue HTTP-Methode QUERY: Das erste neue Verb seit 16 Jahren

Dieser Beitrag basiert auf dem Artikel „The new HTTP method: QUERY” von Tykok auf DEV Community. Den englischen Originaltext findest du unter dev.to/tykok/the-new-http-method-query-2bec.

Im Juni 2026 wurde mit RFC 10008 die erste neue Standard-HTTP-Methode seit 16 Jahren verabschiedet. Seit PATCH im Jahr 2010 gab es keine Erweiterung des HTTP-Verb-Sets mehr. Die neue Methode heißt QUERY und adressiert ein konkretes Problem, das Entwickler seit Jahren mit Workarounds lösen: komplexe Abfragen, die weder in eine URL passen noch die Semantik von POST verdienen.

Key Takeaways (TL;DR)

• Erste neue HTTP-Methode seit 2010: QUERY wurde im Juni 2026 per RFC 10008 standardisiert.
• Bestes aus GET und POST: Request Body erlaubt (wie POST), aber idempotent und cachebar (wie GET).
• Sicher wiederholbar: Bei Netzwerkabbrüchen kann die Anfrage ohne Risiko erneut gesendet werden.
• URI für die Abfrage selbst: Der Server kann eine permanente URL für die Abfrage erzeugen, nicht nur für das Ergebnis.
• Adoption: Noch kaum Server- oder Client-Support. Breite Verfügbarkeit wird für 2027 bis 2028 erwartet.

Das Problem mit GET

GET ist die korrekte Methode, um Ressourcen abzurufen. Filter und Suchparameter werden als Query-Parameter in die URL geschrieben.

GET /orders?select=surname,givenname,email&limit=10&match="email=*@example.*"

Das funktioniert für einfache Abfragen. Für komplexe Filter stößt der Ansatz an mehrere Grenzen. URLs haben Größenlimits von häufig 8.000 Zeichen. Parameter landen in Logs und sind damit ein Sicherheitsrisiko. Komplexe Abfragen wie SQL-Ausdrücke, JSONPath oder verschachtelte Filterobjekte lassen sich schlecht oder gar nicht in Query-Strings abbilden. Und das korrekte Encoding von Sonderzeichen wird bei steigender Komplexität zunehmend fehleranfällig.

Warum POST keine Lösung ist

Der naheliegende Workaround ist POST. Der Body nimmt beliebig komplexe Daten auf und hat kein Größenlimit.

POST /orders HTTP/1.1
Host: api.example.org
Content-Type: application/x-www-form-urlencoded

select=surname,givenname,email&limit=10&match="email=*@example.*"

POST löst das Größenproblem, erzeugt aber neue. POST ist nicht idempotent. Wenn das Netzwerk abbricht, kann ein erneuter Request unbeabsichtigte Seiteneffekte erzeugen. Standard-HTTP-Caching greift nicht, weil Proxies und CDNs POST-Responses in der Regel nicht cachen. Intermediaries können nicht entscheiden, ob ein POST sicher wiederholbar ist. Jedes Framework implementiert eigene Mechanismen wie Idempotency-Keys oder Nonces, um dieses Problem zu umgehen.

QUERY: Das Beste aus beiden Welten

QUERY kombiniert die semantische Sicherheit von GET mit dem Body von POST.

QUERY /orders HTTP/1.1
Host: api.example.org
Content-Type: application/json
Accept: application/json

{
  "select": ["surname", "givenname", "email"],
  "limit": 10,
  "match": { "email": "*@example.*" }
}

Die Methode hat fünf zentrale Eigenschaften:

Kein URL-Größenlimit. Der Request Body kann SQL-Abfragen, JSONPath-Ausdrücke oder beliebig verschachtelte Filterobjekte enthalten.

Idempotent. Zehn identische Requests liefern dasselbe Ergebnis wie ein einzelner.

Safe. QUERY verändert niemals den Serverstatus. Es ist eine reine Leseoperation.

Cachebar. Proxies, CDNs und Browser können Responses cachen, genau wie bei GET.

Sicher wiederholbar. Bei Netzwerkabbrüchen kann die Anfrage ohne Risiko erneut gesendet werden. Keine doppelten Einträge, keine Korruption.

Idempotenz konkret erklärt

Eine Operation ist idempotent, wenn mehrere identische Aufrufe dasselbe Ergebnis erzeugen wie ein einzelner.

✅ GET  /users/123  → 1 Aufruf = 10 Aufrufe = gleiche Daten
✅ QUERY /users     → Wiederholung = gleiches Ergebnis
❌ POST  /users     → 1 Aufruf = 1 User, 2 Aufrufe = 2 User

Das ist entscheidend für die Zuverlässigkeit verteilter Systeme. Wenn der Client nicht weiß, ob die Anfrage angekommen ist, muss er sie wiederholen können, ohne Seiteneffekte zu riskieren.

URI für die Abfrage statt für das Ergebnis

Ein besonderes Feature von QUERY ist die Möglichkeit, eine permanente URL für die Abfrage selbst zu erzeugen. Bei einem klassischen POST zeigt die Content-Location auf das Ergebnis:

POST /orders → 200 OK
Content-Location: /results/xyz789

Bei QUERY kann der Server einen Location-Header zurückgeben, der auf die gespeicherte Abfrage verweist:

QUERY /orders → 200 OK
Location: /saved-queries/42

Ein späterer GET /saved-queries/42 führt dieselbe Abfrage erneut aus und liefert aktuelle Daten. Das ermöglicht drei konkrete Anwendungsfälle: Abfragen per Link mit Kollegen teilen, Suchen als Bookmark speichern und periodische Abfragen ohne erneutes Senden des Body wiederholen.

Auswirkungen auf das REST-API-Design

QUERY verändert die Art, wie Lese-Endpoints strukturiert werden. Statt für jeden Filterfall einen eigenen Endpoint anzulegen:

GET /api/users/active
GET /api/users/inactive
GET /api/users/premium

Gibt es einen einzigen Endpoint mit flexiblem Body:

QUERY /api/users
Content-Type: application/json

{ "status": "active" }

Das reduziert die Anzahl der Routen, vereinfacht Monitoring und Security-Konfiguration und macht die API wartbarer. In Kombination mit dem Adapter-Port-Pattern lässt sich die Abfrage-Logik sauber hinter einem Interface kapseln, das verschiedene Query-Strategien austauschbar macht.

Vergleich: GET vs. POST vs. QUERY

Eigenschaft	GET	POST	QUERY
Safe (read-only)	✅ Ja	❌ Nein	✅ Ja
Idempotent	✅ Ja	❌ Nein	✅ Ja
Body erlaubt	❌ Nein	✅ Ja	✅ Ja
Cachebar	✅ Ja	⚠️ Komplex	✅ Ja
Sicher wiederholbar	✅ Ja	❌ Riskant	✅ Ja
URI für die Abfrage	✅ Standard	❌ Nein	✅ Optional

Aktueller Deployment-Status

QUERY ist seit Juni 2026 per RFC 10008 offiziell standardisiert. Die Implementierung in Servern, Frameworks und Clients steht noch am Anfang. Sehr wenige HTTP-Server und Client-Bibliotheken unterstützen die Methode bereits nativ. Eine breite Adoption wird für 2027 bis 2028 erwartet.

Für den produktiven Einsatz ist es aktuell zu früh. Wer heute eine REST-API plant, sollte die Methode konzeptionell berücksichtigen und die Abfrage-Logik so strukturieren, dass ein späterer Wechsel von POST auf QUERY mit minimalem Aufwand möglich ist.

Checkliste: QUERY in der eigenen API-Architektur vorbereiten

1. Abfrage-Logik vom HTTP-Layer trennen. Die Filterlogik gehört in einen eigenen Service oder eine dedizierte Query-Klasse. Der Controller sollte nur den Transport handhaben.
2. Komplexe Filter als JSON-Body modellieren. Auch wenn der Endpoint heute noch POST nutzt, die Payload als strukturiertes JSON statt als Query-String zu definieren macht die spätere Migration auf QUERY trivial.
3. Idempotenz sicherstellen. Lese-Endpoints dürfen keinen Serverstatus verändern. Wenn ein POST-basierter Such-Endpoint heute Seiteneffekte hat (Logging in eine Business-Tabelle, Zähler-Inkrement), muss das vor einem Wechsel auf QUERY bereinigt werden.
4. Framework-Support beobachten. Die Changelogs von Express, NestJS, Symfony, Spring Boot und den gängigen HTTP-Clients (Axios, HttpClient, Guzzle) auf QUERY-Support prüfen.