HTTP has had the same core methods since the 1990s \u2014 GET, POST, PUT, PATCH, DELETE. They’ve served the web well. But one scenario has always been awkward: complex searches that need a request body.<\/p>\n
RFC 10008, published in 2026, formalizes the HTTP QUERY method \u2014 a new HTTP verb specifically designed for safe, idempotent requests that carry a body. Here’s what it is, why it exists, and what it means for your API design.<\/p>\n
Consider a complex search request. You want to search for orders that:<\/p>\n
How do you send this in a GET request? You encode it as query parameters:<\/p>\n
GET \/api\/orders?date_from=2026-07-01&date_to=2026-07-25&status[]=pending&status[]=processing&states[]=MP&states[]=MH&min_value=50000&categories[]=electronics&categories[]=furniture&reps[]=user_42&reps[]=user_67\r\n\r\n# This URL is 250+ characters and becomes completely unreadable\r\n# Some proxies and servers truncate URLs at 2048 characters\r\n# Complex nested filters become nearly impossible<\/code><\/pre>\nThe alternative \u2014 use POST:<\/p>\n
POST \/api\/orders\/search\r\nContent-Type: application\/json\r\n\r\n{\r\n \"filters\": {\r\n \"date_range\": { \"from\": \"2026-07-01\", \"to\": \"2026-07-25\" },\r\n \"status\": [\"pending\", \"processing\"],\r\n \"client_states\": [\"MP\", \"MH\"],\r\n \"min_value\": 50000,\r\n \"categories\": [\"electronics\", \"furniture\"],\r\n \"assigned_reps\": [\"user_42\", \"user_67\"]\r\n }\r\n}<\/code><\/pre>\nThis works but it’s semantically wrong. POST means “create something” or “perform an action with side effects.” A search has no side effects \u2014 it’s a read-only operation. Using POST for reads violates REST semantics, confuses caching layers, and creates problems for documentation tools.<\/p>\n
This is the gap HTTP QUERY fills.<\/p>\n
What RFC 10008 Defines<\/h2>\n
The HTTP QUERY method has these characteristics:<\/p>\n
\n- Safe:<\/strong> like GET \u2014 it doesn’t modify server state<\/li>\n
- Idempotent:<\/strong> like GET \u2014 calling it multiple times returns the same result<\/li>\n
- Has a request body:<\/strong> unlike GET \u2014 it can carry a structured query payload<\/li>\n
- Cacheable:<\/strong> responses can be cached like GET responses<\/li>\n
- Not a side-effect operation:<\/strong> unlike POST \u2014 it’s purely for retrieving data<\/li>\n<\/ul>\n
QUERY \/api\/orders HTTP\/1.1\r\nHost: api.softcrony.com\r\nContent-Type: application\/json\r\nAccept: application\/json\r\n\r\n{\r\n \"filters\": {\r\n \"date_range\": { \"from\": \"2026-07-01\", \"to\": \"2026-07-25\" },\r\n \"status\": [\"pending\", \"processing\"],\r\n \"client_states\": [\"MP\", \"MH\"],\r\n \"min_value\": 50000,\r\n \"categories\": [\"electronics\", \"furniture\"],\r\n \"assigned_reps\": [\"user_42\", \"user_67\"]\r\n },\r\n \"sort\": { \"field\": \"created_at\", \"direction\": \"desc\" },\r\n \"pagination\": { \"page\": 1, \"per_page\": 20 }\r\n}<\/code><\/pre>\nThe response is identical to what you’d return from a GET \u2014 just data, no side effects:<\/p>\n
HTTP\/1.1 200 OK\r\nContent-Type: application\/json\r\nCache-Control: private, max-age=60\r\n\r\n{\r\n \"data\": [...],\r\n \"meta\": {\r\n \"total\": 147,\r\n \"page\": 1,\r\n \"per_page\": 20\r\n }\r\n}<\/code><\/pre>\nHow It Differs from GET and POST<\/h2>\n
\n\n\nProperty<\/th>\n GET<\/th>\n POST<\/th>\n QUERY<\/th>\n<\/tr>\n<\/thead>\n \n\nSafe (no side effects)<\/td>\n \u2705<\/td>\n \u274c<\/td>\n \u2705<\/td>\n<\/tr>\n \nIdempotent<\/td>\n \u2705<\/td>\n \u274c<\/td>\n \u2705<\/td>\n<\/tr>\n \nRequest body<\/td>\n \u274c (technically allowed but discouraged)<\/td>\n \u2705<\/td>\n \u2705<\/td>\n<\/tr>\n \nCacheable<\/td>\n \u2705<\/td>\n \u274c (by default)<\/td>\n \u2705<\/td>\n<\/tr>\n \nSemantic meaning<\/td>\n Retrieve resource<\/td>\n Create\/action<\/td>\n Query\/search<\/td>\n<\/tr>\n \nBookmarkable<\/td>\n \u2705<\/td>\n \u274c<\/td>\n \u274c (body not in URL)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nImplementing HTTP QUERY in Laravel<\/h2>\n
Laravel’s router doesn’t natively support QUERY yet, but you can handle it:<\/p>\n
\/\/ routes\/api.php \u2014 register QUERY method route\r\nuse Illuminate\\Support\\Facades\\Route;\r\n\r\nRoute::match(['QUERY'], '\/orders', [OrderController::class, 'query']);\r\nRoute::match(['QUERY'], '\/products', [ProductController::class, 'query']);\r\nRoute::match(['QUERY'], '\/clients', [ClientController::class, 'query']);<\/code><\/pre>\n<?php\r\n\r\nnamespace App\\Http\\Controllers\\Api;\r\n\r\nuse App\\Http\\Controllers\\Controller;\r\nuse App\\Http\\Resources\\OrderResource;\r\nuse App\\Models\\Order;\r\nuse Illuminate\\Http\\Request;\r\nuse Illuminate\\Http\\Resources\\Json\\AnonymousResourceCollection;\r\n\r\nclass OrderController extends Controller\r\n{\r\n \/**\r\n * Handle HTTP QUERY requests for searching orders.\r\n *\/\r\n public function query(Request $request): AnonymousResourceCollection\r\n {\r\n $validated = $request->validate([\r\n 'filters' => 'array',\r\n 'filters.date_range' => 'array',\r\n 'filters.date_range.from' => 'date',\r\n 'filters.date_range.to' => 'date',\r\n 'filters.status' => 'array',\r\n 'filters.status.*' => 'in:pending,processing,completed,cancelled',\r\n 'filters.client_states' => 'array',\r\n 'filters.min_value' => 'numeric|min:0',\r\n 'filters.max_value' => 'numeric',\r\n 'filters.categories' => 'array',\r\n 'filters.assigned_reps' => 'array',\r\n 'sort' => 'array',\r\n 'sort.field' => 'string|in:created_at,total_value,client_name',\r\n 'sort.direction' => 'in:asc,desc',\r\n 'pagination' => 'array',\r\n 'pagination.page' => 'integer|min:1',\r\n 'pagination.per_page' => 'integer|min:1|max:100',\r\n ]);\r\n\r\n $filters = $validated['filters'] ?? [];\r\n $sort = $validated['sort'] ?? ['field' => 'created_at', 'direction' => 'desc'];\r\n $pagination = $validated['pagination'] ?? ['page' => 1, 'per_page' => 20];\r\n\r\n $query = Order::query()\r\n ->with(['client', 'items', 'assignedRep'])\r\n ->when(isset($filters['date_range']), function ($q) use ($filters) {\r\n $q->whereBetween('created_at', [\r\n $filters['date_range']['from'],\r\n $filters['date_range']['to'],\r\n ]);\r\n })\r\n ->when(!empty($filters['status']), function ($q) use ($filters) {\r\n $q->whereIn('status', $filters['status']);\r\n })\r\n ->when(!empty($filters['client_states']), function ($q) use ($filters) {\r\n $q->whereHas('client', function ($q) use ($filters) {\r\n $q->whereIn('state', $filters['client_states']);\r\n });\r\n })\r\n ->when(isset($filters['min_value']), function ($q) use ($filters) {\r\n $q->where('total_value', '>=', $filters['min_value']);\r\n })\r\n ->when(isset($filters['max_value']), function ($q) use ($filters) {\r\n $q->where('total_value', '<=', $filters['max_value']);\r\n })\r\n ->when(!empty($filters['categories']), function ($q) use ($filters) {\r\n $q->whereHas('items.product', function ($q) use ($filters) {\r\n $q->whereIn('category', $filters['categories']);\r\n });\r\n })\r\n ->when(!empty($filters['assigned_reps']), function ($q) use ($filters) {\r\n $q->whereIn('assigned_rep_id', $filters['assigned_reps']);\r\n })\r\n ->orderBy($sort['field'], $sort['direction']);\r\n\r\n $results = $query->paginate(\r\n $pagination['per_page'],\r\n ['*'],\r\n 'page',\r\n $pagination['page']\r\n );\r\n\r\n return OrderResource::collection($results);\r\n }\r\n}<\/code><\/pre>\nClient-Side Implementation<\/h2>\n\/\/ JavaScript \u2014 sending HTTP QUERY requests\r\nasync function searchOrders(filters, sort, pagination) {\r\n const response = await fetch('\/api\/orders', {\r\n method: 'QUERY',\r\n headers: {\r\n 'Content-Type': 'application\/json',\r\n 'Accept': 'application\/json',\r\n 'Authorization': `Bearer ${token}`,\r\n },\r\n body: JSON.stringify({ filters, sort, pagination }),\r\n });\r\n\r\n if (!response.ok) throw new Error('Search failed');\r\n return response.json();\r\n}\r\n\r\n\/\/ Usage\r\nconst results = await searchOrders(\r\n {\r\n date_range: { from: '2026-07-01', to: '2026-07-25' },\r\n status: ['pending', 'processing'],\r\n min_value: 50000,\r\n },\r\n { field: 'created_at', direction: 'desc' },\r\n { page: 1, per_page: 20 }\r\n);<\/code><\/pre>\nFallback for Older Clients<\/h2>\n
Some HTTP clients and proxies don’t support custom methods yet. A safe fallback pattern:<\/p>\n
\/\/ Support both QUERY and POST with method override header\r\n\/\/ routes\/api.php\r\nRoute::match(['QUERY', 'POST'], '\/orders\/search', [OrderController::class, 'query'])\r\n ->middleware('api');\r\n\r\n\/\/ Client \u2014 use X-HTTP-Method-Override for compatibility\r\nasync function searchOrders(filters) {\r\n \/\/ Try QUERY first\r\n try {\r\n return await fetch('\/api\/orders', {\r\n method: 'QUERY',\r\n headers: { 'Content-Type': 'application\/json' },\r\n body: JSON.stringify(filters),\r\n });\r\n } catch {\r\n \/\/ Fallback to POST with method override\r\n return await fetch('\/api\/orders\/search', {\r\n method: 'POST',\r\n headers: {\r\n 'Content-Type': 'application\/json',\r\n 'X-HTTP-Method-Override': 'QUERY',\r\n },\r\n body: JSON.stringify(filters),\r\n });\r\n }\r\n}<\/code><\/pre>\nCaching HTTP QUERY Responses<\/h2>\n
Since QUERY is safe and idempotent, responses can be cached. The cache key includes the request body:<\/p>\n
<?php\r\n\r\n\/\/ Laravel middleware \u2014 cache QUERY responses\r\nclass CacheQueryResponses\r\n{\r\n public function handle(Request $request, Closure $next)\r\n {\r\n if ($request->method() !== 'QUERY') {\r\n return $next($request);\r\n }\r\n\r\n \/\/ Cache key = route + body hash\r\n $cacheKey = 'query:' . $request->path() . ':' . md5($request->getContent());\r\n\r\n if (Cache::has($cacheKey)) {\r\n return response()->json(Cache::get($cacheKey))\r\n ->header('X-Cache', 'HIT');\r\n }\r\n\r\n $response = $next($request);\r\n\r\n Cache::put($cacheKey, $response->getData(), 60); \/\/ 60 seconds\r\n\r\n return $response->header('X-Cache', 'MISS');\r\n }\r\n}<\/code><\/pre>\nBrowser and Tool Support in 2026<\/h2>\n
\n\n\nTool\/Environment<\/th>\n QUERY Support<\/th>\n<\/tr>\n<\/thead>\n \n\nfetch() API (browsers)<\/td>\n \u2705 Works \u2014 fetch allows any method string<\/td>\n<\/tr>\n \nAxios<\/td>\n \u2705 Works \u2014 pass method: ‘QUERY’<\/td>\n<\/tr>\n \nPostman<\/td>\n \u2705 Supported in custom method field<\/td>\n<\/tr>\n \ncurl<\/td>\n \u2705 curl -X QUERY …<\/td>\n<\/tr>\n \nLaravel HTTP client<\/td>\n \u2705 Http::send(‘QUERY’, $url, […])<\/td>\n<\/tr>\n \nSome enterprise proxies<\/td>\n \u26a0\ufe0f May block unknown methods \u2014 test your stack<\/td>\n<\/tr>\n \nAWS API Gateway<\/td>\n \u26a0\ufe0f Requires explicit QUERY method configuration<\/td>\n<\/tr>\n \nCloudflare<\/td>\n \u2705 Passes through unknown methods by default<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nWhen to Use QUERY vs GET vs POST<\/h2>\n
Use GET when:<\/strong> The search fits comfortably in URL parameters. Simple filters \u2014 status, date, category. URLs should be bookmarkable and shareable.<\/p>\nUse QUERY when:<\/strong> Complex nested filters that don’t fit in a URL. Structured search payloads with multiple filter types. You want proper REST semantics for read-only operations. You need response caching for expensive search operations.<\/p>\nUse POST when:<\/strong> The operation has side effects (creating, triggering, updating). You’re working with systems that can’t support custom HTTP methods. The “search” also triggers logging, analytics, or other state changes.<\/p>\nRFC 10008 is a recent standard and real-world adoption will take time. But the pattern it formalizes \u2014 safe body-carrying requests \u2014 is one that good API designers have been working around for years. Now there’s a proper name and spec for it.<\/p>\n