Support for HTTP QUERY method

[bpolaszek]

Retrieving data, especially collections, is possible today through the GET HTTP method.

Unfortunately, passing criteria is often cumbersome: everything has to rely on the query string, which has the following drawbacks:

• Everything is a string by design
• Hard to submit composite/complex data structures
• Some browsers may limit the total size of the query string

One could be tempted to use POST to address these issues, but:

• POST isn't considered safe: it is assumed that using this verb will alter the application state
• POST requests are not cachable by design

---

Introducing the QUERY HTTP method ✨

The QUERY verb has been standardized in the HTTP specification as of February 2024 (during the draft phrase, it was initially named SEARCH) - and it's basically "GET - with a body" 🕺.

Its goal is to:

• Retrieve data, like GET does, but with a body (meaning properly typed json is 100% acceptable 🤩)
• Be safe (doesn't alter application state)
• Be idempotent (multiple calls produce the same results)
• Be cacheable (like GET).

From the spec:

	GET	QUERY	POST
Safe	yes	yes	potentially no
Idempotent	yes	yes	potentially no
URI for query	yes (by definition)	optional (Location response field)	no
URI for result	optional (Content-Location response field)	optional (Content-Location response field)	optional (Content-Location response field)
Cacheable	yes	yes	yes, but only for future GET or HEAD requests
Content (body)	"no defined semantics"	expected (semantics per target resource)	expected (semantics per target resource)

Symfony recently introduced its support as of 7.4.

Would you consider supporting it out of the box in Api-Platform in a near future?

[dunglas]

It's still an I-D, not a RFC yet.

[bpolaszek]

My bad - how standards get adopted are a bit obscure to me, I initially understood that QUERY was officially accepted a few months ago.

[dunglas]

It's still a draft mostly because of' this review IIUC: https://datatracker.ietf.org/doc/review-ietf-httpbis-safe-method-w-body-11-httpdir-early-fielding-2025-06-20/

[soyuka]

As API Platform is based on the Symfony HTTP Foundation you can create your custom Query operation that uses the QUERY method and enable deserialize: true in my opinion it should work.

[bpolaszek]

Thanks, I'll give it a try!