Die HTTP QUERY-Methode für Frontend-Teams: Sichere Lesevorgänge mit Body

Die Such- und Filteransichten weisen ein wiederkehrendes API-Problem auf. Wenn man jeden Filter in einen GET-Abfragesatz kodiert, wird die URL lang und unhandlich; sendet man die Filter als JSON per POST, verwendet man eine Methode, die einen Zustandswechsel signalisiert, obwohl es sich eigentlich um eine Leseoperation handelt. Die HTTP QUERY-Methode wurde genau für dieses Problem entwickelt. Dieser Artikel erklärt, was QUERY bedeutet, wie man sie von einer React-Anwendung aus mit fetch senden kann, sowie welche Komponenten des Systems – von CORS bis zu Caches – beachtet werden müssen, bevor man sich darauf verlassen kann.

Das Problem, das QUERY löst

Eine Produktliste mit nur wenigen Filtern erzeugt schnell eine Anfrage wie diese:

/products?category=laptop&brand=Apple&minPrice=50000&maxPrice=150000&rating=4

Das funktioniert zwar, doch jeder neue Filter verlängert den String. Verschachtelte oder wiederholte Werte (mehrere Marken, Preisbereich, Sortierordnung, Paginierung) erfordern spezielle Kodierungsregeln, und sehr lange URLs können bei Servern, Proxys und Protokollen auf Längenbeschränkungen stoßen.

Der übliche Ausweg ist POST mit einem JSON-Body. Das ist auf der Client-Seite einfacher umzusetzen, verschleiert aber den Vertrag. POST ist weder sicher noch idempotent – daher können Zwischeninstanzen nicht davon ausgehen, dass eine solche Anfrage harmlos genug ist, um wiederholt zu werden. Caches speichern standardmäßig keine Antworten, und jeder, der die API liest, muss in der Dokumentation nachschauen, um zu erfahren, dass diese spezielle POST-Anfrage nur Daten liest.

Was QUERY ist

QUERY ist eine HTTP-Methode, mit der ein Server aufgefordert wird, eine im Anfrageinhalt beschriebene Abfrage auszuführen. Laut Berichten zum Zeitpunkt der Erstellung veröffentlichte das IETF sie im Juni 2026 als Standard unter RFC 10008; prüfen Sie den aktuellen Status dieses RFCs, bevor Sie darauf verweisen. Anstatt Parameter in die URL einzubauen, sendet der Client sie im Body:

QUERY /products HTTP/1.1
Content-Type: application/json

{
  "category": "laptop",
  "brands": ["Apple", "Dell"],
  "price": {
    "min": 50000,
    "max": 150000
  }
}

Der Server bewertet die Anfrage und gibt die entsprechenden Ergebnisse zurück. Was QUERY von POST unterscheidet, ist seine Semantik: Es wird als sicher definiert, was bedeutet, dass es die Zielressource nicht ändert, sowie als idempotent, was bedeutet, dass ein zweimaliger Versand denselben Effekt hat wie ein einmaliger Versand. Genau diese beiden Eigenschaften ermöglichen es Clients, Proxys und Caches, es wie eine Leseoperation zu behandeln. Idempotenz bedeutet beispielsweise, dass ein Client oder Zwischenagent eine fehlgeschlagene QUERY automatisch erneut versuchen kann, ohne das Risiko von doppelten Nebenwirkungen einzugehen – etwas, was bei POST nicht der Fall sein sollte.

Auswahl zwischen GET, POST und QUERY

QUERY ersetzt die anderen Methoden nicht. Jede hat weiterhin eine klare Aufgabe:

• GET bleibt die Standardmethode für einfache Abfragen: eine Ressource anhand ihrer ID oder eine kurze Liste mit wenigen einfachen Parametern.

POST bleibt die Methode für Operationen, die den Serverzustand erstellen oder ändern, oder die nicht sicher wiederholt werden können.

QUERY eignet sich für Lesevorgänge, deren Eingabe komplex genug ist, um strukturierte Inhalte zu erfordern – wie verschachtelte Filter, Wertarrays oder Abfragesprachen.

Für die Frontend-Entwicklung ist der Vorteil, dass komplexe Filterzustände direkt in den Anfragekörper übertragen werden können, und der API-Vertrag macht klar, dass nichts geändert wird.

Absendung einer QUERY-Anfrage von React

Stellen Sie sich eine React-Komponente vor, die ihre aktuellen Produktfilter in einem Objekt speichert:

const filters = {
  category: "laptop",
  brands: ["Apple", "Dell"],
  price: {
    min: 50000,
    max: 150000
  },
  rating: 4
};

Mit QUERY kann dieses Objekt serialisiert und unverändert gesendet werden. Der untenstehende Helper verwendet fetch mit einem benannten Methodennamen sowie einem JSON-Körper:

const searchProducts = async (filters) => {
  const response = await fetch("/api/products", {
    method: "QUERY",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(filters)
  });

Der zweite Teil derselben Funktion überprüft den Antwortstatus und parsert das Ergebnis:

  if (!response.ok) {
    throw new Error("Failed to fetch products");
  }  return response.json();
};

Ausgenommen der Methodenbezeichnung ist dies identisch mit einem POST-Aufruf. Die Änderung ist semantischer als syntaktischer Natur: Der Anfrage wird nun mitgeteilt, dass es sich um eine Abfrage handelt. Beachten Sie zwei praktische Aspekte: Der Fetch-Standard verschiebt nur einige bekannte Methodennamen in Großbuchstaben, daher sollten Sie immer "QUERY" in Großbuchstaben schreiben. Im Gegensatz zu GET und HEAD, die fetch nicht mit einem Body senden darf, ist es bei QUERY erlaubt, einen Body zu übertragen.

Ein Kompromiss betrifft insbesondere Benutzeroberflächen: Filter, die im URL kodiert sind, können als Lesezeichen gespeichert und geteilt werden sowie nach einem Seitenaufruf erhalten bleiben. Ein QUERY-Body hingegen nicht. Wenn teilebare Links wichtig sind, möchten Sie möglicherweise den Filterzustand trotzdem im Client in die Seiten-URL einbeziehen, während Sie die strukturierte Abfrage an die API senden.

Überprüfen Sie die Unterstützung entlang des gesamten Anfragenpfads

Eine standardisierte Methode bedeutet nicht, dass jedes Komponente, das mit Ihrem Traffic in Berührung kommt, sie versteht. Eine Browseranfrage durchläuft mehrere Schichten, bevor sie die Anwendung erreicht, und jede dieser Schichten kann eine unbekannte Methode ablehnen oder verfälschen. Bevor Sie QUERY einsetzen, überprüfen Sie Folgendes:

• Das Verhalten des Browsers sowie von fetch() in den von Ihnen unterstützten Browsern.
• Die CORS-Konfiguration in der API.
• API-Gateways und Reverse-Proxy-Server.
• CDNs und Edge-Caches.
• Authentifizierungs- und Autorisierungs-Middleware.
• Tools zur Überwachung, Protokollierung und Traceability.
• Die Routing- und Body-Parsing-Funktionen des Backend-Frameworks.

Einige Schichten erlauben möglicherweise nur eine feste Liste von Methoden, und wieder andere werfen bei unerkannten Methoden den Request-Body weg. Testen Sie in einem Umfeld, das die Produktionsumgebung widerspiegelt, end-to-end – nicht nur gegen einen lokalen Server.

CORS erfordert immer eine Prüfanfrage

QUERY gehört nicht zu den in der CORS-Sicherheitsliste aufgeführten Methoden (GET, HEAD und POST). Das bedeutet, dass eine cross-originale QUERY-Anfrage vom Browser immer einen Präfluganruf auslöst: Vor der eigentlichen Anfrage sendet der Browser eine OPTIONS-Anfrage, um zu prüfen, ob QUERY erlaubt ist.

Falls Ihre React-Anwendung und die API sich auf unterschiedlichen Ursprungsdomänen befinden, muss der Server auf diesen Präfluganruf mit einem Access-Control-Allow-Methods-Header antworten, der QUERY sowie alle von Ihrer Anfrage verwendeten Header wie Content-Type enthält. Ein JSON-Body erzwingt bereits für POST einen Präfluganruf, sodass die zusätzlichen Kosten oft keine Neuigkeit sind – doch die Methode muss ausdrücklich aufgeführt werden.

Das wird bei der Entwicklung leicht übersehen. Tools wie Postman und curl stellen keine CORS-Vorgaben durch, wodurch ein Endpunkt dort perfekt funktionieren kann und im Browser fehlschlägt.

Caching ist möglich, aber aufwändiger

Die Antworten auf QUERY-Anfragen sind cachierbar, was einer der Hauptvorteile dieser Methode gegenüber POST ist. Die Komplikation besteht darin, dass die Antwort vom Inhalt des Anfragenkörpers abhängt und nicht nur von der URL. Betrachten Sie diese beiden Anfragenkörper, die an denselben Endpunkt gesendet werden:

{
  "brand": "Apple"
}

{
  "brand": "Dell"
}

Sie müssen unterschiedliche Ergebnisse liefern. Daher muss ein Cache beim Entscheiden, ob eine gespeicherte Antwort wiederverwendet werden kann, den Inhalt der Anfrage sowie in der Regel auch deren Medientyp im Cache-Schlüssel berücksichtigen. Caches können den Inhalt außerdem normalisieren (zum Beispiel unwesentlichen Leerzeichen in JSON ignorieren), damit äquivalente Abfragen denselben Eintrag teilen.

Für Entwickler von React und Next.js bedeutet das, QUERY bei der Caching-Strategie nicht als „GET mit Anfragenkörper“ zu betrachten. Browser-HTTP-Caches, CDN-Systeme sowie die fetch-Caches auf Framework-Ebene berücksichtigen möglicherweise noch nicht den Anfragenkörper im Schlüssel, daher sollte man das Verhalten jeder Ebene überprüfen, anstatt von Cache-Erfolgen auszugehen.

Wie QUERY mit GraphQL zusammenhängt

GraphQL taucht oft im selben Kontext auf, doch die beiden arbeiten auf unterschiedlichen Ebenen. GraphQL bietet eine Sprache zur Beschreibung der gewünschten Daten sowie ein Modell zur deren Abfrage. QUERY hingegen ist lediglich ein Verb auf Transportebene: Es legt fest, wie eine Anfrage mit Abfraginhalt von HTTP behandelt werden soll. GraphQL-Client senden heutzutage üblicherweise Operationen mit POST; ein GraphQL-Server könnte grundsätzlich auch Leseoperationen über QUERY akzeptieren, doch QUERY ersetzt GraphQL nicht, und die beiden können je nach Design der API nebeneinander existieren.

Sollten Sie bestehende APIs migrieren?

In der Regel nicht, zumindest nicht nur wegen des Existenz von QUERY. Wenn ein Suchendpunkt bereits gut über GET oder POST funktioniert, führt ein Wechsel dazu, dass zusätzliche Migrations- und Kompatibilitätsarbeiten erforderlich sind – mit begrenztem Nutzen. QUERY macht am meisten Sinn beim Entwurf eines neuen Endpunkts, dessen Anfragen:

• nur zum Lesen dienen.

Möglicherweise komplex.

Kann natürlicher als strukturierte Inhalte ausgedrückt werden als als URL-Parameter.

Kann von sicheren, idempotenten Semantiken wie Wiederholungsversuchen und Caching profitieren.

Es bietet Teams eine prinzipiengerechte Alternative dazu, stets auf POST zurückzugreifen, sobald eine GET-Anfrage unhandlich wird.

Haupterkenntnisse

• Verwenden Sie GET für einfache Abfragen und halten Sie einfache Aufrufe einfach.
• Betrachten Sie QUERY für komplexe, nur-Lese-Anfragen, die einen strukturierten Inhalt benötigen.
• Erwarten Sie keine Geschwindigkeitssteigerung: QUERY ändert nur, wie die Anfrage dargestellt wird, nicht die Geschwindigkeit des Backends oder des Netzwerks.
• Überprüfen Sie vor der Produktivnutzung die Unterstützung in Browsern, Proxys, Gateways, CDNs sowie Ihrem Backend-Framework.
• Konfigurieren Sie CORS so, dass die Methode ausdrücklich erlaubt wird, und testen Sie dies in einem echten Browser.
• Stellen Sie sicher, dass alle Schlüssel der Cache-Ebenen im Anfragekörper überprüft werden, bevor Sie sich auf gespeicherte QUERY-Antworten verlassen.
• Achten Sie auf die Adoption im Ökosystem: Suchseiten, Dashboards und datenintensive Anwendungen sind die Bereiche, in denen QUERY voraussichtlich am schnellsten Vorteile bringt.