The HTTP Query Method

📝 Discussion Summary (Click to expand)

The Hacker News discussion around the proposed QUERY HTTP method reveals three primary, strongly debated themes:

1. The Conflict Between Semantic Purity and Practical Need

A central theme is the tension between strictly adhering to established HTTP semantics (where GET is safe and POST is for state change) and the practical need to perform "read" operations that require a request body (often due to URL length limits or complex filtering).

Supporting Quote: Users acknowledge the real-world motivation, noting that existing practices often break semantics: > "The cases tend to look like this:
- An endpoint was implemented as a GET endpoint, since it’s for getting data, with the search terms in the query parameters. The search term got too long, breaking a critical behavior in production environments." (gbear605)

2. The Interoperability and Infrastructure Problem of Modifying GET

Many users argue that simply allowing bodies on existing GET requests is fundamentally broken because the infrastructure of the internet (proxies, CDNs, load balancers, firewalls) is explicitly designed to ignore or strip bodies from GET requests, sometimes seeing them as security risks (request smuggling).

Supporting Quote: Experienced users emphasize that infrastructure actively fights against anomalous GET requests: > "Your GET request can modify state. But if your request exceeds a browser’s timeout threshold, the browser will retry it. And then you get to spend a few days debugging why a certain notification is always getting sent three times (ask me how I know this)" (notatoad) > > "Sending a GET request with a body is just asking for all sorts of weird caching and processing issues." (LudwigNagasena)

3. The Value of a New Standard Verb vs. Server-Side Documentation

There is a significant split on whether introducing a new method (QUERY) is beneficial for signaling intent to intermediaries, or whether it's unnecessary overhead, arguing that the behavior should simply be documented (e.g., a POST with specific idempotent guarantees) on the server side.

Supporting Quote (Pro-New Verb): Those in favor see the new verb as crucial for middleware and infrastructure to correctly interpret safety/caching expectations without needing to parse URLs or rely on out-of-band documentation: > "The semantics are important. GET APIs are expected to be safe, idempotent, and cache-friendly. When you are unable to use GET for technical reasons and move to POST, suddenly none of the infrastructure (like routers, gateways, or generic http libs) can make these assumptions about your API." (flakes)
Supporting Quote (Against New Verb): Critics argue that the distinction is solely a server constraint and that the client protocol should remain simple, favoring POST or sticking to existing patterns: > "The interpretation of a request is up to the server... QUERY semantics vs generic POST semantics is a receive/server-side decision and thus should not be a syntactic element of client requests, merely a server description of endpoint semantics." (Veserv)

🚀 Project Ideas

Infrastructure-Aware Endpoint Validator/Linter

Summary

A static analysis tool or browser extension that audits API interaction code (e.g., JavaScript in SPAs, or server-side client libraries) for adherence to idiomatic HTTP verb usage, specifically flagging instances where POST is used for idempotent fetching, which the new QUERY method aims to solve.
Core value proposition: Provides early feedback on semantic misalignment, helping developers adopt the new QUERY verb (or stick to GET/POST correctly) and avoid middleware breakage caused by assumed semantics (like infinite retries on non-idempotent POSTs to read endpoints).

Details

Key	Value
Target Audience	API developers using modern frontends (SPAs) or backend services that consume third-party/internal APIs.
Core Feature	Analyzes source code or intercepted network requests, flagging reads currently implemented as `POST` (with body) as candidates for migration to `QUERY` (if standardized) or marking them as potentially confusing `POST` operations.
Tech Stack	Language Server Protocol (LSP) integration for IDEs, targeting JavaScript/TypeScript (for client-side use) and Python/Go (for server-side HTTP clients). Could integrate with tools like ESLint/Prettier.
Difficulty	Medium
Monetization	Hobby

Notes

Why HN commenters would love it: Directly addresses the confusion around using POST for fetching: "New employees repeatedly come in and are confused why it’s not a GET endpoint, or why it doesn’t modify anything." It enforces the "cognitively useful" separation of concerns that users value.
Potential for discussion or practical utility: It formalizes the discussion about semantic purity into a practical tool for engineering teams struggling with API hygiene and middleware compatibility issues (e.g., logging, retries).

HTTP Header-Based Semantics Negotiator Proxy

Summary

A lightweight, user-configurable proxy server (or set of server modules for Nginx/Envoy) designed to sit in front of existing infrastructure, allowing legacy systems to use the POST-as-QUERY pattern without breaking downstream proxies/caches.
Core value proposition: Bridges the gap between the desire for HTTP body semantics (for large queries) and the reality that intermediate infrastructure might strip bodies from standard GET requests, or mishandle non-standard methods like future QUERY. It translates the POST-as-QUERY pattern into a standardized QUERY request if the infrastructure supports it, or enforces server-side caching promises via custom headers if not.

Details

Key	Value
Target Audience	Infrastructure/DevOps engineers managing complex server meshes (CDNs, load balancers, API Gateways) that need to support evolving HTTP semantics.
Core Feature	Intercepts `POST` requests targeting known "fetch-only" endpoints (identified via configuration or perhaps by inspecting response headers from the origin server). Translates the POST body into a format digestible by caches, or attempts to rewrite the method to `QUERY` (if the intermediate layer supports it) while ensuring safety/idempotence assertions are passed through via standard HTTP headers.
Tech Stack	Go or Rust (for high-performance proxy/layer implementation), integrating with Envoy Filter APIs or Nginx Lua Module.
Difficulty	High
Monetization	Hobby

Notes

Why HN commenters would love it: Addresses the middleware/proxy concerns: "if your request exceeds a browser’s timeout threshold, the browser will retry it. And then you get to spend a few days debugging why a certain notification is always getting sent three times..." This tool helps system designers maintain control over retry and caching logic in legacy environments.
Potential for discussion or practical utility: It provides a practical, pragmatic solution for SREs who must maintain stability while waiting for full ecosystem adoption of new RFCs, as mentioned: "I don’t think it’s unreasonable to expect your sysadmins... to set up these services correctly."

API Documentation/Client Generator Focused on Server Constraints

Summary

A tool that parses API definitions (like OpenAPI/Swagger or custom DSLs) and specifically calls out when an endpoint requires a body for fetching, automatically generating client code that uses the standardized QUERY method (once adopted) or, failing that, explicitly marks the POST operation as a "Documented Fetch Operation" requiring custom handling (like server-side caching configuration).
Core value proposition: Automates the documentation and client generation for these ambiguous read/body operations, making the server's non-standard choice explicit to clients and infrastructure providers, thus mitigating confusion among new team members.

Details

Key	Value
Target Audience	API authors creating schemas intended for consumption by multiple client teams or public services.
Core Feature	Extends OpenAPI/JSON Schema specification to enforce a new `x-http-semantics` field. If `read_only: true` is set alongside `requestBody` containing data, the generator outputs warnings and suggests `QUERY` or explicitly generates client code showing the potential risk of using POST for reads.
Tech Stack	Node.js/TypeScript for parsing and template generation (e.g., for TypeScript, Python, or Java clients). Should integrate tightly with existing schema validation tooling.
Difficulty	Medium
Monetization	Hobby

Notes

Why HN commenters would love it: It tackles the need for discoverability and standardized understanding: "The point is to have a standard, so you can more easily learn what an API is doing instead of having to start from scratch every time." This shifts responsibility from the consumer to the documented contract.
Potential for discussion or practical utility: It sets a standard for API contracts that explicitly addresses the "Query with body" use case, which others noted is already being used in production (e.g., Elasticsearch, GraphQL).