Beyond GET and POST: Architecting APIs with the New HTTP QUERY Method (RFC 10008)

The HTTP Method Dilemma: Why GET and POST Aren't Enough

For decades, web developers and system architects have operated under a rigid compromise when designing APIs. The REST architectural style dictates that retrieving data should be safe and idempotent, mapping naturally to the HTTP GET method. However, real-world application requirements frequently clash with this ideal.

When building complex search interfaces, analytics dashboards, or graph-based query engines (such as GraphQL or custom JSON-based query languages), the parameters required to filter and fetch data can easily grow to several kilobytes. This presents a critical engineering challenge.

Historically, developers have had to choose between two flawed workarounds:

1. Bloating the URL with GET Query Parameters: Passing massive, nested JSON objects or base64-encoded search filters within the URL query string. This approach frequently hits the URI length limits imposed by browsers, reverse proxies, and Content Delivery Networks (CDNs)—often capped at 2,048 or 8,192 characters. Furthermore, query parameters are routinely logged in plaintext by web servers, application performance monitoring (APM) tools, and proxies, posing a severe security risk if the query contains sensitive user data or PII (Personally Identifiable Information).

2. Abusing the POST Method: Creating endpoints like POST /users/search where the query configuration is sent safely inside the HTTP request body. While this bypasses URL length limits and logging issues, it fundamentally violates HTTP semantics. In HTTP, POST is neither safe nor idempotent. It is designed to change server state. Because of this, standard HTTP clients, CDNs, and web browsers cannot safely retry failed requests on connection drops, nor can they cache the response of a search query without highly complex, custom configurations.

This architectural friction has remained unresolved for years. But with the introduction of RFC 10008, the Internet Engineering Task Force (IETF) has finally standardized a clean, elegant solution: the HTTP QUERY method.

Enter RFC 10008: The HTTP QUERY Method

RFC 10008 introduces a new, dedicated HTTP request method specifically designed for safe, idempotent data retrieval using a request body.

The QUERY method acts as a semantic hybrid. It combines the safety and idempotency of GET with the payload-carrying capabilities of POST.

Here is a typical RFC 10008 compliant HTTP request:

QUERY /contacts HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  'filter': {
    'status': 'active',
    'tags': ['enterprise', 'lead']
  },
  'projection': ['id', 'name', 'email']
}

In this example, the request body specifies exactly what data needs to be retrieved, avoiding the constraints of the URL. The backend parses this body and returns the requested resources, all while honoring the standard HTTP rules for safe retrieval.

Under the Hood: Semantics and Characteristics of QUERY

To fully leverage RFC 10008, developers must understand its core semantic characteristics:

1. Safety and Idempotency

Like GET and HEAD, QUERY is defined as safe and idempotent. This means that executing a QUERY request must not alter the state of the target resource. Additionally, executing the same QUERY multiple times must yield the same result (assuming the underlying database hasn't changed via other write operations).

Because it is safe and idempotent, client libraries and service meshes can automatically retry failed QUERY requests over flaky networks without the risk of duplicating transactions or creating unintended side effects.

2. Request Body Semantics

Unlike GET, where the presence of a request body has undefined semantics and is rejected by many servers, the request body of a QUERY request is the primary vehicle for defining the query parameters. The content type of the body is explicitly defined by the Content-Type header (e.g., application/json, application/graphql, or text/plain).

3. Response Caching

One of the most powerful aspects of RFC 10008 is its support for caching. Responses to QUERY requests can be cached by browsers, edge proxies, and CDNs. However, because the query parameters reside in the request body rather than the URL, caching proxies must calculate the cache key using both the Request URI and the request body (or a cryptographic hash of the body).

QUERY vs. GET vs. POST: A Technical Comparison

| Feature | GET | POST | QUERY (RFC 10008) | | :--- | :--- | :--- | :--- | | Has Request Body | No (Undefined/Ignored) | Yes | Yes | | Safe | Yes | No | Yes | | Idempotent | Yes | No | Yes | | Cacheable | Yes (By Default) | No (Rarely/With Headers) | Yes (Using URI + Body) | | URL Length Limits | Vulnerable | Immune | Immune | | Plaintext Log Risk | High | Low | Low |

Practical Implementation: Simulating QUERY in Modern Architectures

While RFC 10008 is an official standard, full native support across all web servers, browsers, and CDNs is still evolving. Fortunately, because HTTP is an extensible protocol, you can start implementing and supporting the QUERY method today in your custom services.

Let's look at how to handle a QUERY request in a modern Go backend using the standard net/http package:

package main

import (
	'encoding/json'
	'fmt'
	'net/http'
)

type UserQuery struct {
	Status string   `json:'status'`
	Roles  []string `json:'roles'`
}

func handleUsers(w http.ResponseWriter, r *http.Request) {
	// Check if the request method is QUERY
	if r.Method == 'QUERY' {
		var query UserQuery
		err := json.NewDecoder(r.Body).Decode(&query)
		if err != nil {
			http.Error(w, 'Invalid JSON body', http.StatusBadRequest)
			return
		}

		// Simulate fetching data from database based on query
		w.Header().Set('Content-Type', 'application/json')
		w.WriteHeader(http.StatusOK)
		fmt.Fprintf(w, `{'status':'success', 'matches': 42, 'filters_applied': '%s'}`, query.Status)
		return
	}

	// Fallback or method not allowed
	http.Error(w, 'Method Not Allowed', http.StatusMethodNotAllowed)
}

func main() {
	http.HandleFunc('/users', handleUsers)
	http.ListenAndServe(':8080', nil)
}

In this Go example, we explicitly handle the custom QUERY method. Modern network routers, reverse proxies (like Nginx, Envoy, or HAProxy), and application frameworks generally pass unrecognized HTTP methods directly to the upstream application, making it surprisingly easy to adopt QUERY incrementally.

Caching, Security, and CDN Considerations

To securely and efficiently deploy RFC 10008 in production, you must address two critical architectural components:

1. Cache Key Computation

Standard CDNs and reverse proxies (like Varnish) generate cache keys using the HTTP method and the URI (e.g., GET /api/v1/users). For QUERY, this is insufficient because two different request bodies to the same URI will yield different datasets.

To cache QUERY responses, your caching layer must support request body hashing. For instance, in Varnish Cache, you can customize the vcl_hash subroutine to include a hash of the request body in the cache key. As CDN vendors roll out native RFC 10008 support, this process will become fully automated.

2. Security at the Edge

Web Application Firewalls (WAFs) are traditionally optimized to inspect the body of POST and PUT requests for malicious payloads (like SQL Injection or Cross-Site Scripting). When implementing QUERY, ensure your WAF rules are updated to inspect the body of QUERY requests as well. Failing to do so can create a blind spot where attackers execute malicious queries undetected.

The Road to Adoption: What Lies Ahead

RFC 10008 marks a significant milestone in the evolution of web protocols. By resolving the long-standing semantic tension between GET and POST, it provides API architects with a clean, standardized tool for managing complex data operations.

While client-side libraries (like fetch in browsers or axios) and edge network providers are still working on first-class integrations, the backend ecosystem is already fully capable of supporting QUERY. By adopting this method, you can future-proof your API designs, optimize network performance, and maintain strict adherence to pure HTTP semantics.