Your Guide to the New HTTP QUERY Method

When querying complex systems, query strings can get quite lengthy at times. They may even be too large for some systems to process. Traditionally, some developers have gotten around this limitation by sending assets using POST. This can negatively impact performance, though, as the call may end up in the cache. It can even compromise security and anonymity as there are often records made of POST requests.

Developers have been calling for the implementation of a new HTTP method for some time to address some of these issues. Those hopes have been answered, as the IETF has just published the standards for HTTP QUERY Method.

To help you get started with this new tool, we’ve put together a guide to the HTTP Query request method.

Understanding the HTTP QUERY Method

Both GET and POST have their limitations when it comes to querying. URL strings can become prohibitively long if you’re creating a complicated query, which can cause issues if your query exceeds a certain character length. Some frameworks also have size limitations, which can cause your API call to get rejected if it’s too large. Different components also have further restrictions, which can cause your API call to get lost in a limbo of caches and rejections.

GET isn’t ideal for filtering data, either. It’s not ideal for returning specific fields, for instance. You also have to know the particular identifiers you’re trying to access.

Traditionally, developers have gotten around this restriction by using a combination of POST and assets sent in the body. POST requests have limitations, though, as it’s still not immediately apparent that a query is being performed.

The QUERY method splits the difference between GET and POST. Like POST, it also sends assets as part of the request. It also makes it clear that an idempotent query is being made. Previously, programmers often had to do a GET POST GET do-si-do to send a query, create a resource, and then receive a response.

QUERY rolls all of that into one as the query and an asset in the body are included in the call. It also prevents having to make a new resource every time you want to query the API, which does wonders for API performance.

QUERY requests are safe to use, as they can’t alter the resources they access. However, servers can be allocated more resources if a QUERY request exceeds its limitations.

QUERY requests are expected to return some form of an asset when they’re completed. A request that returns no content might be addressed with a 204 No Response result. 3xx Redirects can also be returned via a Location header field.

QUERY requests can be made during specific instances, as well. For example, you can specify a QUERY request for files created past a certain date using an If-Modified-Since parameter.

Caching in QUERY

QUERY responses can be cached. These cached responses can be used to generate additional QUERY responses, provided they meet certain criteria.

The QUERY method documentation also offers some best practices to keep in mind to improve cache efficiency. Particularly, HTTP QUERY requests should remove content encoding and normalize using specific file conventions as indicated in the Content-Type field.

Accept-QUERY

QUERY can be invoked in specific circumstances using the Accept-Query header field. For example, a server might institute a QUERY for a specific file type. Multiple file types can be specified via a comma-separated list.

Example QUERY Requests

Here are a few examples of QUERY in action as specified by the IETF documentation.

A simple query with a direct response:

QUERY /contacts HTTP/1.1
   Host: example.org
   Content-Type: example/query
   Accept: text/csv

   select surname, givenname, email limit 10

And the response:

   HTTP/1.1 200 OK
   Content-Type: text/csv

   surname, givenname, email
   Smith, John, john.smith@example.org
   Jones, Sally, sally.jones@example.com
   Dubois, Camille, camille.dubois@example.net

A simple QUERY request with an indirect response:

QUERY /contacts HTTP/1.1
   Host: example.org
   Content-Type: example/query
   Accept: text/csv

   select surname, givenname, email limit 10

And the response:

   HTTP/1.1 303 See Other
   Location: http://example.org/contacts/query123

   Fetch Query Response:

   GET /contacts/query123 HTTP/1.1
   Host: example.org

   Response:

   HTTP/1.1 200 OK
   Content-Type: text/csv

   surname, givenname, email
   Smith, John, john.smith@example.org
   Jones, Sally, sally.jones@example.com
   Dubois, Camille, camille.dubois@example.net

QUERY in Action

Let’s take a quick look at a real-world application for QUERY to help give you some ideas for implementation in your own projects.

In a LinkedIn post, developer Alex Corkins offers an example from his work in Agri-Tech. He first highlights that a main limitation of GET is that you might not know all of the specific IDs. Using GET, this could look like:

HTTP GET /animals/${the_identifier_i_know}?identifierType=${the_identifier_type}

However, this approach can get rather large, as you might be dealing with an extensive collection of objects. He then offers an example of what a request might look like using a POST request:

{
  "knownAnimalIdentifier":[
    "id1",
    "id3",
    "id3"
  ],
  "where":{
    "healthTreatment":{
      "condition":"mastitis",
      "product":"amyzin"
    }
  }
}

As you can see, the POST request method handles many of the same issues that QUERY addresses. The problem is that it’s not idempotent, meaning a new resource needs to be created for each call. QUERY, on the other end, creates a fixed resource for all of your query results.

Finally, Corkins discusses some of his reasoning for preferring QUERY over GET and POST. Most importantly, QUERY adds intent and clarity to an API. Querying via GET doesn’t necessarily let the system know that a query is being performed.

QUERY Method: Final Thoughts

Data-intensive API calls will only become more prevalent as we continue to produce and consume more and more data. This means that query URLs will keep getting longer and more complicated. This runs the risk of some of your data filters getting cut off if they exceed the limit. It also means you have to more or less create your own query language with every API call.

Having to know specific IDs is a stumbling block for an API’s usefulness, as well. The ability to return data from unknown items is reason enough to investigate QUERY in your own development projects.

QUERY is still brand new, though, keep in mind. It might be a while until it is widely supported or adopted. This alone could cause performance issues as the unrecognized format could get caught up in cache limbo. However, there are more than enough potential uses for HTTP QUERY to make it warrant investigation and experimentation.