HTTP Query fixes the method. Not the promise.

Everyone seems to be talking about HTTP QUERY right now. That is not a bad thing. RFC 10008 closes a real gap in HTTP by defining a method for safe and idempotent requests with request content. In practice, it gives queries a cleaner place when GET becomes awkward and POST feels wrong.

Photo by Fabio Sasso on Unsplash

This was overdue. For years, API designers had to make an uncomfortable choice: either push more and more query information into the URL, with the usual pain around length, encoding, readability, logging, and operational behavior, or use POST for something that does not create anything, does not change anything, and is really a read. RFC 10008 gives that situation a proper name and a proper method. It deserves the attention it gets.

Still, I am not sure the most interesting question is the method.

The method looks right. The offer remains unclear.

Take a reporting API. A consumer wants revenue numbers by region, product group, customer segment, month, channel, and a few additional filters that depend on internal business logic. The query does not belong into a URL anymore. POST feels semantically lazy. HTTP QUERY looks right. At the HTTP level, it probably is.

But the more important question is what the provider has actually offered. Is this a reporting capability, a flexible analytics interface, or simply a polite way to query internal data structures from the outside? Those are not small variations of the same design. They are different offers, with different expectations, different responsibilities, and different risks.

This is where the current discussion can become too narrow. HTTP QUERY makes the request more honest. It does not make the API promise clearer.

GraphQL and OData are reminders, not rivals.

Complex querying over APIs is not new. GraphQL did not become relevant because people needed another way to spell POST. It became relevant because consumers often need data in shapes that do not follow provider-side resource boundaries.

OData did not become relevant because URLs were too short. It became relevant because enterprises needed conventions for filtering, selecting, expanding, sorting, metadata, and discoverability across structured data APIs.

Both deal with queryability, but not merely as transport. HTTP QUERY sits underneath that. It gives HTTP a better method for a specific class of interactions. Useful, yes. But it does not define the query language, the right amount of consumer freedom, or the safe boundary of the underlying model. That work remains.

A capability is more than query access.

The word I keep coming back to here is capability. Not as another architecture label, but as a discipline question.

If the API offers “monthly revenue insight by region”, the provider can shape that interaction, document the assumptions, test the performance, govern the lifecycle, and support consumers around a recognizable business need. If the API offers “run a flexible query over revenue-related data”, the provider is making a very different promise.

That second promise may still be valid. But it needs different governance, different limits, different observability, probably different pricing, and certainly a different conversation with consumers. Too often we treat these as small design variants. They are not. They are different products hiding behind similar request shapes.

Synchronous means: answer now.

This becomes even more visible in the synchronous case. HTTP QUERY will be tempting because it cleans up a synchronous interaction. A client sends a query. The server returns a result. No awkward POST. No oversized GET. The surface looks better.

For bounded lookups, filtered searches, and well-understood query forms, that can be exactly right. But many queries that look like reads do not behave like simple reads. Reporting, analytics, compliance evidence, and AI-supported evaluation can quickly become expensive, variable, probabilistic, or dependent on multiple sources.

A synchronous API says: I can answer now. That sentence is heavier than it looks. It implies latency expectations, retry behavior, timeout assumptions, and a provider that understands the cost and variability of the query well enough to make the interaction reliable.

HTTP QUERY does not remove any of that. It only gives the interaction a better HTTP shape.

Some queries should not return immediately.

Sometimes HTTP QUERY is enough. Sometimes it is exactly the moment where the better design is not another synchronous request, but a query resource.

In that model, the consumer creates a query, the provider accepts it under known conditions, the status becomes visible, and the result can be retrieved when it is ready. Depending on the context, the result can also be cached, audited, reused, or expired. RFC 10008 itself acknowledges the idea that servers can assign URIs to the query itself or to a specific query result for later use.

This model is less elegant at first glance. It introduces another resource. It asks consumers to deal with state. But that may be the honest model. Not every question deserves the fiction of immediate answerability.

Cleaner semantics do not create a better API.

This is where HTTP QUERY becomes useful, but also misleading. It improves the surface of an interaction. The method is more precise. The intent is less blurry. The old POST workaround becomes less necessary.

That is good engineering work. But a cleaner method can also make a weak design look more deliberate than it is. A vague query interface does not become a well-designed capability because the method is now correct. An unbounded reporting endpoint does not become operationally safe because the request is safe and idempotent. A synchronous interaction does not become reliable because the protocol semantics are better.

HTTP QUERY belongs where the provider can describe the query, bound it, operate it, and support it as part of a clear offer. If that is not possible, the issue is probably not the missing method anymore. It is the design of the API itself.

What remains after RFC 10008.

The useful discussion starts after the method choice. Once the HTTP semantics are clear, the harder design questions become more visible: the query model the interaction needs, the amount of consumer freedom the provider can responsibly allow, the commitment the provider is actually making, and whether the interaction is a capability, a data access shortcut, or a job pretending to be a read.

RFC 10008 fixes an ambiguity in HTTP. That is valuable. But the harder ambiguity often remains in the offer behind the API. And that is not something a new method can standardize away.