Brand new HTTP QUERY method

Many years ago, people way more intelligent than most of us proposed the World Wide Web. There was a need to create a communication protocol that would allow people to retrieve HTML documents. In 1996, the first official version was released. It was HTTP/1.0. It has since evolved into a backbone of the internet. Most of the data sent on the internet uses HTTP protocol.

But there can be many different types of data sent. Some of them just ask for a resource, some want to create some resources, some want to update or delete something. That's why HTTP protocol defines HTTP methods. They tell the server what kind of request is coming. There has not been any major change to them... Up until recently! After over 16 years, a new method was introduced: QUERY, which is defined in RFC 10008.

Quick method recap

HTTP Method names are pretty self-explanatory. GET retrieves information, POST sends the information, PUT updates, DELETE deletes, and so on. Every method has assigned specific semantics and expectations. For example, POST method is expected to change the data, whereas GET is expected to not modify data in any way. This is an important reason why QUERY was introduced.

What is QUERY used for?

QUERY was specifically designed for, as its name suggests, querying data. Now, you might be asking: "Well, we already have a method for it and it's GET". You are really close with your thinking but not quite. You see, previously developers had two options to get the data: GET and POST. Why POST? You might ask, and you are right to ask.

Problems with GET

GET method is great for simple queries, but it lacks in many places. Let's say you want to send a complicated query to a server. Request body semantics of a GET request are not defined and some systems might reject such a request. So we are left with using web address to send information. This has its own disadvantages. You might exceed address length limit, address can be stored in logs after TLS termination and leak confidential data. Encoding advanced query into a URI-compatible string is also a rather complicated problem.

Why not POST then?

This was the method used for such situations. Just put relevant data for a query inside the request body and call it a day, just remember to not mutate anything on the server. Size and privacy problem is mitigated. However, this does not communicate. safety. We cannot be sure resource was not modified (especially if we are integrating with a third-party API), so we can't automatically retry such a request. We can't assume it's just a harmless lookup. A POST request might not be idempotent.

Idempotency means that repeating the same request has the same intended effect on server state as sending it once. Safety means that the client does not request or expect a state change to the target resource.

Now QUERY comes into place!

Want to put query data in the request body? Want your request to be idempotent? Use QUERY! It combines best from both worlds. It behaves similarly to a GET request - no mutations, caching, idempotency, but allows query data to be sent inside the body.

When to use?

• It naturally fits into search tools and search APIs. It allows you to implement complicated or long search condition which is safe to retry.
• When handling private data. Request content is generally less likely than a URI to appear in logs, but it is not private by default.
• Queries that take long time. Instead of calculating long query every time, we can just cache it and serve to user.

Watch out for compatibility!

QUERY method is still quite new and it support is uneven. You should ensure your userbase is ready to handle it before going into production.