HTTP QUERY method (RFC 10008)
The HTTP QUERY method is a safe and idempotent HTTP method, like GET, that carries request content in the body, like POST. It is standardised by RFC 10008 (June 2026). MuxMaster has supported QUERY as a first-class method since v1.2.0: it has its own constant, its own registration helpers on *Mux and *Group, and the same dispatch, Allow header, and redirect handling as every other method the router accepts.
When to use QUERY
The HTTP QUERY method that MuxMaster supports is defined in RFC 10008, Section 2 as follows:
The QUERY method is used to initiate a server-side query. Unlike the GET method, which requests a representation of the resource identified by the target URI (as defined by Section 7.1 of [HTTP]), the QUERY method is used to ask the target resource to perform a query operation within the scope of that target resource.
The content of the request and its media type define the query. The origin server determines the scope of the operation based on the target resource.
In a MuxMaster application, QUERY is the method for a read-only request whose parameters are too large or too structured for a URL query string. A GET request can only carry its parameters in the URL; a POST request can carry a body, but POST is neither safe nor idempotent, so clients, proxies, and caches cannot retry or reuse it. A QUERY request carries the query document in the body and keeps the safe and idempotent guarantees of GET, as defined in RFC 10008 §2.
Typical uses of a QUERY route in MuxMaster are search endpoints that accept a JSON filter document, reporting endpoints with many criteria, and APIs that forward a query language (for example SQL or GraphQL text) in the request body.
The MuxMaster QUERY API
MuxMaster exposes one constant and five registration methods for the HTTP QUERY method. All of them are defined in mux.go and group.go at v1.3.0.
| Symbol | Signature | Purpose |
|---|---|---|
MethodQuery |
const MethodQuery = "QUERY" |
The QUERY method token, for use with Handle, HandleFunc, HandleE, HandleFast, Match, and in tests. |
Mux.QUERY |
func (m *Mux) QUERY(pattern string, h http.HandlerFunc) |
Registers an http.HandlerFunc for QUERY requests on pattern. |
Mux.QUERYE |
func (m *Mux) QUERYE(pattern string, h HandlerFuncE) |
Registers an error-returning handler; a returned error goes to Mux.ErrorHandler, or produces a 500 when no handler is set. |
Mux.QUERYFast |
func (m *Mux) QUERYFast(pattern string, h FastHandler) |
Registers a FastHandler, which receives the path parameters as a third argument. |
Group.QUERY |
func (g *Group) QUERY(path string, h http.HandlerFunc) |
Registers an http.HandlerFunc for QUERY requests under the group prefix. |
Group.QUERYE |
func (g *Group) QUERYE(path string, h HandlerFuncE) |
Registers an error-returning handler for QUERY requests under the group prefix. |
MuxMaster's Group has no QUERYFast method; a fast QUERY route on a MuxMaster group is registered with Group.HandleFast(muxmaster.MethodQuery, path, h), as the upstream test TestQueryMethod_Group_HandleFast_NoDedicatedShortcut does.
Each MuxMaster QUERY helper is a shorthand for the generic registration call with MethodQuery: mux.QUERY(p, h) registers the same route as mux.HandleFunc(muxmaster.MethodQuery, p, h), and mux.QUERYFast(p, h) the same route as mux.HandleFast(muxmaster.MethodQuery, p, h).
Step 1 — Register a QUERY route
A QUERY route in MuxMaster is registered like any other route: call Mux.QUERY (or Group.QUERY) with a path pattern and an http.HandlerFunc. Path parameters, groups, and middleware registered with Pre and Use apply to QUERY routes exactly as they apply to GET or POST routes.
Steps 1 and 2 together form a complete main.go. It starts with this package clause and these imports:
package main
import (
"encoding/json"
"log"
"mime"
"net/http"
"github.com/FlavioCFOliveira/MuxMaster"
)
func main() {
mux := muxmaster.New()
mux.QUERY("/books/search", searchBooks)
log.Fatal(http.ListenAndServe(":8080", mux))
}
The same QUERY route can be registered with MuxMaster's generic API as mux.Handle(muxmaster.MethodQuery, "/books/search", http.HandlerFunc(searchBooks)). On a group, api := mux.Group("/api/v1") followed by api.QUERY("/books/search", searchBooks) registers /api/v1/books/search.
Step 2 — Validate the request content in the handler
A MuxMaster QUERY handler must validate the Content-Type header and the body itself, because the router performs no validation of either. RFC 10008 §2.1 requires the server to fail a QUERY request whose Content-Type is missing or inconsistent with the content (400 Bad Request), whose media type it does not support (415 Unsupported Media Type), or whose content it cannot process (422 Unprocessable Content). The handler below accepts JSON only, limits the body to 1 MiB, and advertises its accepted format with the Accept-Query response header defined in RFC 10008 §3.
// BookQuery is the query document a client sends in the QUERY request body.
type BookQuery struct {
Author string `json:"author"`
Year int `json:"year"`
}
func searchBooks(w http.ResponseWriter, r *http.Request) {
// RFC 10008 §2.1: the router does not check Content-Type; the handler must.
mediaType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
if err != nil {
http.Error(w, "missing or invalid Content-Type", http.StatusBadRequest)
return
}
if mediaType != "application/json" {
http.Error(w, "unsupported query format", http.StatusUnsupportedMediaType)
return
}
var q BookQuery
if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&q); err != nil {
http.Error(w, "malformed query", http.StatusBadRequest)
return
}
// RFC 10008 §3: advertise the accepted query format.
w.Header().Set("Accept-Query", `"application/json"`)
_ = muxmaster.JSON(w, http.StatusOK, map[string]any{"author": q.Author, "year": q.Year, "results": []string{}})
}
This excerpt uses only the standard library and the MuxMaster v1.3.0 API (encoding/json, mime, net/http, muxmaster.JSON). It was compiled and exercised against MuxMaster v1.3.0 for this page: a JSON QUERY request returned 200, a QUERY request without Content-Type returned 400, and a text/plain request returned 415. The upstream cookbook recipe shows a variant of the same handler.
Step 3 — Call the QUERY route with curl
Send a QUERY request to the MuxMaster route with curl by setting the method with -X QUERY, the media type with -H, and the query document with --data.
curl -i -X QUERY http://localhost:8080/books/search \
-H 'Content-Type: application/json' \
--data '{"author":"Ursula K. Le Guin","year":1969}'
The response to this QUERY request carries 200 OK, the header Accept-Query: "application/json", and the JSON body written by the handler. Sending the same command without the Content-Type header returns 400 Bad Request from the handler, not from the MuxMaster router.
Method dispatch: ANY, Allow, 405, and OPTIONS
MuxMaster treats the HTTP QUERY method as a member of its fixed method set, so the router's method-level behaviours include QUERY:
ANYregisters QUERY. MuxMaster'sMux.ANYandGroup.ANYregister the handler for GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, CONNECT, TRACE, and QUERY. Since v1.2.0, a QUERY request to anANYroute reaches its handler; in v1.1.0 it received405or404.Matchaccepts QUERY. In MuxMaster,mux.Match([]string{http.MethodGet, muxmaster.MethodQuery}, "/m", h)registershfor both methods.405 Method Not Allowedlists QUERY. WhenHandleMethodNotAllowedistrue(the default), MuxMaster answers a request with an unregistered method on a path that has a QUERY route with405and lists QUERY in theAllowheader. With GET and QUERY registered on/books/search, a POST request receivesAllow: GET, QUERY, OPTIONS.- Automatic
OPTIONSlists QUERY. WhenHandleOPTIONSistrue(the default), MuxMaster answers an OPTIONS request to the same path with204 No ContentandAllow: GET, QUERY, OPTIONS. Alloworder. MuxMaster writes theAllowheader in the fixed order GET, HEAD, POST, PUT, PATCH, DELETE, CONNECT, TRACE, QUERY, OPTIONS, as the upstream testTestQueryMethod_AllowHeader_FullOrderasserts.
Redirects preserve the QUERY method and body
MuxMaster redirects a QUERY request with 307 Temporary Redirect, which preserves the method and the body, when RedirectCode is left at its default of 0. This applies to both automatic redirects: RedirectTrailingSlash (on by default) and RedirectFixedPath (off by default). GET and HEAD requests receive 301 Moved Permanently instead. A non-zero Mux.RedirectCode replaces the default for every method, QUERY included; set it to 308 Permanent Redirect if you need a permanent redirect that still preserves the method and body. RFC 10008 §2.5 notes that the exceptions that let clients turn a redirected POST into a GET after 301 or 302 do not apply to QUERY.
With only /books/search registered on a MuxMaster router, a QUERY request to /books/search/ receives 307 with Location: /books/search, and a GET request to the same path receives 301.
What the handler is responsible for
MuxMaster routes a QUERY request to its handler without inspecting the request content. The handler, or middleware the application adds, is responsible for:
- Content validation. Checking the
Content-Typeand the body of a QUERY request and failing with400,415, or422as RFC 10008 §2.1 requires (see Step 2); MuxMaster performs no such check. - Advertising query formats. Setting the
Accept-Queryresponse header (RFC 10008 §3) when the resource wants to advertise the media types it accepts. MuxMaster never sets it. - Caching. RFC 10008 §2.7 makes QUERY responses cacheable, with a cache key that includes the request content. MuxMaster does not implement HTTP response caching; cache headers and any cache in front of the router are the application's responsibility.
- CORS. QUERY is not a CORS-safelisted method, so a browser sends a preflight
OPTIONSrequest before a cross-origin QUERY request (RFC 10008 §4). When you use the MuxMasterCORSmiddleware, list"QUERY"inCORSOptions.AllowedMethods.
Why MuxMaster defines MethodQuery
MuxMaster defines MethodQuery because Go 1.27's net/http package does not define an http.MethodQuery constant; the addition is tracked by the Go project as golang/go#80058. The value of muxmaster.MethodQuery is the string "QUERY", the method token that RFC 10008 registers. If a future Go release adds http.MethodQuery, its value will also be "QUERY", so MuxMaster's constant will remain equal to it; according to the GoDoc of MethodQuery at v1.3.0, MuxMaster does not deprecate or remove the constant when that happens.
Before v1.2.0, MuxMaster panicked when a route was registered for QUERY, for example with Handle("QUERY", …). The panic message was muxmaster: unsupported HTTP method 'QUERY', raised in mux.go at v1.1.0. Since v1.2.0, QUERY is one of the ten methods MuxMaster accepts: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, CONNECT, TRACE, and QUERY.
Common questions
Does MuxMaster support the HTTP QUERY method?
Yes: MuxMaster has supported the HTTP QUERY method defined in RFC 10008 since v1.2.0, released on 2026-09-26.
MuxMaster's QUERY support includes the MethodQuery constant, the Mux.QUERY, Mux.QUERYE, Mux.QUERYFast, Group.QUERY, and Group.QUERYE helpers, QUERY in ANY, and QUERY in the Allow header of 405 and automatic OPTIONS responses.
How do I register a QUERY route in MuxMaster?
In MuxMaster, call mux.QUERY(pattern, handler) with an http.HandlerFunc, for example mux.QUERY("/books/search", searchBooks).
In MuxMaster, use mux.QUERYE for an error-returning QUERY handler, mux.QUERYFast for a FastHandler, group.QUERY or group.QUERYE inside a group, and group.HandleFast(muxmaster.MethodQuery, path, h) for a fast QUERY route on a group.
Which status code does MuxMaster use to redirect a QUERY request?
MuxMaster redirects a QUERY request with 307 Temporary Redirect by default, for both trailing-slash and fixed-path redirects, so the client repeats the QUERY method with the same body.
MuxMaster redirects GET and HEAD with 301 Moved Permanently. A non-zero Mux.RedirectCode overrides the default for every method, QUERY included.
Does MuxMaster validate the Content-Type or body of a QUERY request?
No: the MuxMaster router performs no validation of a QUERY request's Content-Type header or body, so the handler must validate both.
RFC 10008 §2.1 specifies the failures a MuxMaster QUERY handler should return: 400 for a missing or inconsistent Content-Type, 415 for an unsupported media type, and 422 for content that cannot be processed.
Why does MuxMaster define MethodQuery instead of using net/http?
MuxMaster defines MethodQuery because Go 1.27's net/http package has no http.MethodQuery constant yet (golang/go#80058).
The value of MuxMaster's MethodQuery constant is "QUERY" and will remain equal to any future http.MethodQuery, so code that uses it will not need to change.
Sources
Every statement on this page was checked against the upstream MuxMaster source at the v1.3.0 tag and against RFC 10008, except the pre-v1.2.0 panic message, which was checked against the source at the v1.1.0 tag.
mux.go—MethodQuery,Mux.QUERY,Mux.QUERYE,Mux.QUERYFast,ANY, theAlloworder, and the default redirect code.mux.goat v1.1.0 — the pre-v1.2.0 panic messagemuxmaster: unsupported HTTP method 'QUERY'.group.go—Group.QUERY,Group.QUERYE, andGroup.ANY.query_method_test.go— the tests for dispatch,ANY,Match, theAllowheader, and redirects.docs/routing.md— method helpers and redirect status codes.README.md— the supported method set.CHANGELOG.md— the[1.2.0]entry that added QUERY support.release-notes/v1.2.0-20260926.md— the v1.2.0 highlights and upgrade notes (also on this site as Release notes v1.2.0).- RFC 10008: The HTTP QUERY Method — §2 (method definition, quoted above), §2.1 (media types and failure codes), §2.5 (redirection), §2.7 (caching), §3 (
Accept-Query), §4 (security considerations and CORS). - golang/go#80058 — the Go issue that tracks
http.MethodQuery.