La méthode HTTP QUERY

QUERY est une méthode HTTP proposée qui comble un véritable manque : elle est sûre et idempotente comme GET, mais elle peut transporter un corps de requête comme POST. Voyez-la comme « un GET auquel on peut joindre une charge utile ».

Sa raison d’être

Les requêtes complexes ont longtemps imposé un choix inconfortable :

• GET avec une chaîne de requête place chaque filtre dans l’URL. Les URL ont des limites de longueur, sont journalisées en clair et se prêtent mal aux critères structurés ou imbriqués.
• POST avec un corps transporte parfaitement la charge utile, mais ment sur l’intention. POST n’est ni sûre ni idempotente : caches, robots d’exploration et intermédiaires doivent donc supposer que la requête modifie l’état. Ce n’est pas le cas — vous ne faites que lire.

QUERY lève la contradiction : la sémantique dit « ceci est une lecture », et le corps transporte les critères.

Propriétés

À quoi ressemble une requête

QUERY /products HTTP/1.1
Host: shop.example
Content-Type: application/json
Accept: application/json

{ "category": "boots", "inStock": true }

Mise en cache avec Content-Location

Parce que QUERY est sûre et idempotente, une réponse peut être mise en cache — mais la clé de cache ne peut pas être l’URL seule, puisque le corps varie. Le serveur indique l’emplacement canonique du résultat au moyen d’un en-tête Content-Location :

HTTP/1.1 200 OK
Content-Location: /products?category=boots&inStock=true
Cache-Control: max-age=60

Un cache (ou le client) peut alors réutiliser cette représentation pour une requête équivalente. C’est le mécanisme qui permet à une lecture dotée d’un corps de rester cacheable.

Essayez

Rendez-vous sur le Playground et envoyez une véritable requête QUERY au point de terminaison d’écho de ce site pour voir exactement comment la méthode, les en-têtes et le corps parviennent au serveur.

QUERY est définie dans un Internet-Draft de l’IETF et évolue encore. Considérez les détails ci-dessus comme un résumé de travail et consultez le draft lié pour le texte faisant autorité et à jour.