HTTP-QUERY-Methode erklärt: RFC 10008, QUERY vs. GET vs. POST

Die HTTP-QUERY-Methode ist eine neue Request-Methode, definiert in RFC 10008 (Juni 2026), die eine Query im Request-Body sendet und sowohl sicher als auch idempotent ist. Stellen Sie es sich wie GET mit einem Body vor: Sie erhalten den Platz von POST für komplexe Filter und die Garantien von GET für Caching und automatische Wiederholungen.

Wenn Sie einen 3-KB-Filter in eine URL gequetscht haben oder eine schreibgeschützte Suche als POST gesendet haben und zusehen mussten, wie Ihr Cache und Ihre Retry-Logik sie ignorieren, ist QUERY die Lösung. Dieser Leitfaden behandelt, was die Spezifikation sagt, wie QUERY im Vergleich zu GET und POST abschneidet, was es heute unterstützt und wie Sie einen QUERY-Endpunkt mit Ihrem Coding-Agenten testen.

Was ist die HTTP-QUERY-Methode?

QUERY ist eine HTTP-Methode, die die Zielressource auffordert, die im Request-Inhalt beschriebene Query auszuführen und das Ergebnis zurückzugeben. Der Request-Body und sein Content-Type definieren die Query. Die Methode ist sicher (der Client erwartet keine Zustandsänderung) und idempotent (eine Wiederholung hat denselben Effekt), sodass Clients, Proxies und Caches sie wie GET wiederholen und cachen können.

Die Spezifikation ist RFC 10008, „The HTTP QUERY Method“, ein Proposed Standard, der im Juni 2026 von Julian Reschke (greenbytes), James M. Snell (Cloudflare) und Mike Bishop (Akamai) veröffentlicht wurde. IANA hat sie mit „safe: yes, idempotent: yes“ in das HTTP-Methoden-Registry aufgenommen, direkt neben der SEARCH-Methode aus der WebDAV-Ära, die es fast geworden wäre.

Eine QUERY-Anfrage sieht so aus:

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

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

Der Server antwortet mit 200 OK und dem Ergebnis im Body.

Warum GET und POST nicht ausreichten

Vor QUERY hatten Sie zwei Optionen für einen komplexen Lesevorgang, und beide haben Lücken.

GET packt alles in die URL. RFC 10008 nennt vier Probleme damit:

1. Größenbeschränkungen sind im Voraus unbekannt, weil eine Anfrage viele Systeme durchläuft. RFC 9110 empfiehlt lediglich, dass Sender und Empfänger mindestens 8.000 Oktette unterstützen.
2. Das Kodieren strukturierter Daten in eine gültige URI ist verschwenderisch.
3. URIs werden weit häufiger protokolliert und als Lesezeichen gespeichert als Request-Bodies, was bei sensiblen Filtern ein Datenschutzproblem ist.
4. Jede Kombination von Query-Eingaben wird zu einer eigenen Ressource.

GET mit einem Body ist ebenfalls nicht die Antwort. RFC 9110 besagt, dass Inhalt in einer GET-Anfrage keine definierte Semantik hat. Manche Server lesen ihn, manche verwerfen ihn, und manche Proxies lehnen die Anfrage ab. Sie können sich nicht darauf verlassen, dass er den gesamten Pfad übersteht.

POST funktioniert, täuscht aber über die Absicht hinweg. Eine POST-Suche läuft einwandfrei, doch nichts teilt einem Client, Cache, Proxy oder einer Retry-Bibliothek mit, dass der Vorgang schreibgeschützt ist. Also überspringen Caches sie, und Clients wiederholen sie nach einer abgebrochenen Verbindung nicht. Wenn Sie einen Idempotenzschlüssel an einen reinen Lesevorgang anflanschen mussten, nur damit Wiederholungen sicher sind, kennen Sie dieses Problem.

QUERY behält den Body von POST und fügt die Garantien von GET hinzu.

QUERY vs. GET vs. POST

Hier ist der Vergleich, basierend auf Tabelle 1 von RFC 10008:

Die Kurzfassung: Verwenden Sie GET, wenn die Query bequem in die URL passt, QUERY, wenn nicht, und POST nur, wenn die Anfrage den Zustand ändert. Für eine Auffrischung zu den klassischen Methoden lesen Sie unsere Leitfäden zu HTTP-Methoden und GET vs. POST.

Was RFC 10008 definiert

Content-Type ist obligatorisch

Server MÜSSEN eine QUERY ablehnen, deren Content-Type fehlt oder nicht mit dem Body übereinstimmt. Die Spezifikation empfiehlt diese Statuscodes:

• 400 Bad Request: kein Medientyp oder ein Typ, der nicht zum Inhalt passt. Server dürfen den Body nicht sniffen und den Typ dadurch überschreiben.
• 415 Unsupported Media Type: Die Ressource unterstützt dieses Query-Format nicht.
• 422 Unprocessable Content: Das Format ist in Ordnung, aber die Query kann nicht ausgeführt werden, etwa SQL, das eine nicht existierende Tabelle benennt.
• 406 Not Acceptable: Der Client hat einen Antworttyp angefordert, den die Ressource nicht erzeugen kann.

Location und Content-Location

Ein Server kann zwei optionale Header zurückgeben, die eine QUERY in etwas verwandeln, das Sie später per GET abrufen können:

• Content-Location verweist auf das gespeicherte Ergebnis dieses konkreten Laufs. Es kann temporär sein.
• Location verweist auf die gespeicherte Query selbst. Ein GET darauf führt die Query mit frischen Daten erneut aus, ohne den Body erneut zu senden.

Die Spezifikation schlägt vor, dass Clients bei wiederholten Anfragen auf GET auf der Location-URI umsteigen, da das Caching von GET einfacher ist. Wenn Sie einen der beiden Header für eine Query mit sensiblen Daten zurückgeben, SOLLTE die URI keine sensiblen Teile des ursprünglichen Request-Bodys enthalten.

Caching

QUERY-Antworten sind cachefähig. Der Cache-Key MUSS den Request-Inhalt und zugehörige Metadaten wie den Medientyp enthalten. Caches DÜRFEN den Body zuerst normalisieren, zum Beispiel indem sie die Content-Encoding entfernen oder JSON für einen +json-Typ normalisieren, um mehr Treffer zu erzielen. Die Spezifikation warnt, dass eine schlechte Normalisierung die falsche Antwort zurückgeben kann, rechnen Sie also damit, dass CDNs hier vorsichtig sind.

Weiterleitungen

Ein 301, 302, 307 oder 308 bedeutet „dieselbe QUERY an die neue URI senden“. Anders als bei POST darf eine QUERY bei einem 301 oder 302 nicht in GET umgeschrieben werden. Ein 303 See Other bedeutet „das Ergebnis mit einem GET auf dieser URI abrufen“.

Der Accept-Query-Header

Accept-Query ist ein neuer Response-Header, der QUERY-Unterstützung und die Query-Formate bewirbt, die eine Ressource akzeptiert. Es ist eine Structured-Field-Liste, also parsen Sie ihn als solche:

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

Clients können die Unterstützung auch mit OPTIONS entdecken und den Allow-Header lesen oder einfach die QUERY senden und einen 405 Method Not Allowed behandeln.

Welche Tools unterstützen QUERY heute?

Die Unterstützung ist uneinheitlich, testen Sie also Ihren eigenen Stack. Folgendes haben wir am 28. Oktober 2026 bestätigt:

Hier ist der curl-Aufruf, den wir gegen einen lokalen Node-Server verwendet haben:

curl -i -X QUERY http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"q":"running shoe","limit":2}'

Der Fetch-Standard verbietet einen Body nur bei GET und HEAD, daher können Browser QUERY mit einem Body senden. QUERY ist jedoch keine CORS-safelisted Methode, daher löst jede Cross-Origin-QUERY einen Preflight aus. Ihr Server muss QUERY in Access-Control-Allow-Methods auflisten.

Die Lücken liegen in der Mitte des Netzwerks: Reverse-Proxys, API-Gateways, WAFs und CDNs, die Methoden per Allowlist zulassen oder ihren Cache nicht am Body festmachen. Prüfen Sie jeden Hop, bevor Sie ausliefern. Der Newsletter APIs You Won’t Hate merkt an, dass viele Web-Frameworks QUERY bereits direkt oder über Custom-Method-Routing verarbeiten.

Wie Sie QUERY einführen, ohne Clients zu brechen

Sie müssen Ihre POST-Such-Endpunkte nicht entfernen.

1. Fügen Sie QUERY neben der POST-Route hinzu. Richten Sie beide auf denselben Handler. Neue Clients verwenden QUERY; alte funktionieren weiter.
2. Machen Sie es bekannt. Geben Sie Accept-Query auf der Ressource zurück und nehmen Sie QUERY in Allow bei OPTIONS- und 405-Antworten auf.
3. Erzwingen Sie Content-Type. Geben Sie 400 oder 415 zurück, wie die Spezifikation empfiehlt, und 422 für Queries, die zwar geparst werden können, aber nicht ausgeführt werden können.
4. Weichen Sie auf 405 oder 501 aus. Clients sollten denselben Body als POST wiederholen, wenn ein Hop QUERY ablehnt.
5. Korrigieren Sie CORS. Fügen Sie QUERY für Browser-Clients zu Access-Control-Allow-Methods hinzu.
6. Entscheiden Sie über Caching. Aktivieren Sie gemeinsames Caching nur dort, wo Ihr Cache den Body als Key verwendet. Andernfalls geben Sie eine Location-URI zurück und lassen Clients sie per GET abrufen.
7. Dokumentieren Sie es. Definieren Sie in OpenAPI 3.2 den Vorgang unter query: im Path Item:

openapi: 3.2.0
paths:
  /products:
    query:
      summary: Search products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductQuery'
      responses:
        '200':
          description: Matching products

Kurze, einfache Filter können als Query-Strings bei GET bleiben. RFC 10008 selbst sagt, dass GET wahrscheinlich die bessere Wahl ist, wenn Ihre Query so kurz ist.

Lassen Sie Ihren Coding-Agenten einen QUERY-Endpunkt mit der Apidog CLI testen

Eine neue Methode bedeutet, den Happy Path, jeden Fehlercode und die Fallback-Route zu prüfen. Übergeben Sie das an Claude Code, Codex oder Cursor und lassen Sie den Agenten die Apidog CLI steuern.

Installieren Sie die CLI, melden Sie sich an und fügen Sie die Apidog-Skill zu Ihrem Agenten hinzu:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Geben Sie Ihrem Agenten dann einen Prompt:

In Apidog project <projectId>, add a QUERY /products endpoint that takes a
JSON body {q, limit}. Create test cases that assert 200 with an array for a
valid body, 415 for Content-Type text/plain, and 400 with no Content-Type.
Run them against the staging environment and summarize any failures.

Der Agent liest jedes Schema, validiert seine Payload und schreibt erst dann:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

Die endpoint.json, die er schreibt, setzt "method": "query", was das endpoint-create-Schema der CLI neben get, post und den WebDAV-Methoden aufführt. Fügen Sie --upload-report hinzu, um den Lauf in der Apidog-App zu sehen. Derselbe apidog run-Befehl mit -r junit lässt sich in CI einsetzen; siehe wie Sie API-Tests mit apidog run in CI ausführen und wie Sie die Apidog CLI in Claude Code verwenden. Der Free-Tarif von Apidog deckt bis zu 4 Benutzer ab.

FAQ

Ist die HTTP-QUERY-Methode ein offizieller Standard? Ja. RFC 10008 ist ein Standards-Track-RFC mit Status Proposed Standard, veröffentlicht im Juni 2026, und IANA führt QUERY im HTTP Method Registry als sicher und idempotent.

Ist QUERY einfach GET mit einem Body? Fast, aber besser definiert. RFC 9110 gibt einem GET-Body keine Semantik, sodass Intermediäre ihn ignorieren oder ablehnen können. QUERY macht den Body zur Query, erfordert einen Content-Type und nimmt den Body in den Cache-Key auf.

Wann sollte ich QUERY statt POST verwenden? Verwenden Sie QUERY für jede schreibgeschützte Suche oder jeden Filter, der zu groß oder zu sensibel für eine URL ist. Behalten Sie POST für Anfragen bei, die etwas erstellen oder ändern.

Können Browser QUERY-Anfragen senden? Ja, über fetch mit einer benutzerdefinierten Methode. Cross-Origin-QUERY-Anfragen benötigen immer einen CORS-Preflight, daher muss Ihr Server die Methode zulassen.

Werden QUERY-Antworten gecacht? Sie können gecacht werden. Caches müssen den Request-Body und seine Metadaten in den Cache-Key aufnehmen. Viele CDNs und Proxies tun das noch nicht, prüfen Sie also Ihren oder geben Sie eine Location-URI zurück, die Clients per GET abrufen können.

Unterstützt OpenAPI QUERY? OpenAPI 3.2 fügt dem Path Item Object ein query-Feld für QUERY-Operationen hinzu, sodass Sie sie ohne Erweiterungen dokumentieren können.