QUERY; hr; reachable

Two super quick resources and one potential new HTTP verb await Drop readers on this fine Friday.

Since it’s a short one, we’ll save some GPU cycles and do away with the TL;DR section, today.

QUERY

The HTTP QUERY method is a proposed addition to the HTTP protocol that is hoping to improve how complex read operations are handled over the network (more precisely, the internet). Unlike the traditional GET method, which is limited by URL length constraints and encoding issues, QUERY allows clients to send query parameters within the request body while maintaining the semantics of a safe and idempotent operation. This means it can carry request content without side effects, enabling more intricate and expressive queries that are cacheable and suitable for automatic retries.

By defining queries in the request body and supporting any appropriate media type, the QUERY method overcomes the limitations of cramming complex queries into URLs or misusing the POST method for read-only operations. Responses to QUERY requests can include results directly or use redirects, and may contain headers like Content-Location or Location to facilitate retrieving or repeating the query. Although still a draft specification as of September 2024, this is a pretty cool effort to standardize a common need in web APIs, providing a semantically appropriate way to perform complex read operations.

An example is in order:

$ curl \
  --request QUERY \
  --url 'https://api.example.com/weather/historical' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "locations": ["New York", "Los Angeles", "Chicago", "Miami", "Seattle"],
    "dateRange": {
      "start": "2023-01-01",
      "end": "2023-12-31"
    },
    "metrics": ["temperature", "humidity", "precipitation", "wind_speed"],
    "aggregation": "monthly",
    "filters": {
      "temperature": { "min": 0, "max": 35 },
      "precipitation": { "min": 0 }
    },
    "sort": { "by": "temperature", "order": "desc" },
    "limit": 100
  }'

• QUERY helps stand this apart from POST, GET, PUT, etc.
• Like POST, we have a giant request body to work with, so no ? & hieroglyphics in the URL string.
• We also don’t have to worry about maxing out the character limit of the URL path + query parameters.

This is a hypothetical response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /weather/historical/results/12345
Location: /weather/historical/queries/67890
Cache-Control: max-age=3600
Date: Fri, 20 Sep 2024 14:30:00 GMT
Server: ExampleWeatherAPI/1.0

{
  "results": [
    {
      "location": "Miami",
      "date": "2023-07-01",
      "temperature": 32.5,
      "humidity": 75,
      "precipitation": 120,
      "wind_speed": 10
    },
    {
      "location": "Los Angeles",
      "date": "2023-08-01",
      "temperature": 30.2,
      "humidity": 65,
      "precipitation": 0,
      "wind_speed": 8
    },
    {
      "location": "Chicago",
      "date": "2023-07-01",
      "temperature": 29.8,
      "humidity": 70,
      "precipitation": 50,
      "wind_speed": 12
    }
  ],
  "metadata": {
    "totalResults": 1000,
    "queryExecutionTime": "1.2s",
    "dataLastUpdated": "2024-09-20T00:00:00Z"
  },
  "links": {
    "next": "/weather/historical/results/12345?page=2",
    "self": "/weather/historical/queries/67890"
  }
}

• The response includes a Content-Location header, allowing for efficient caching and retrieval of the same query results in the future. We know how long we have to reuse the results thanks to the Cache-Control header, too.
• The Location header provides a URL to retrieve or repeat this specific query, which is valuable for reproducibility in data analysis.
• The response includes metadata about the query execution, which can be crucial for understanding the context of the data and optimizing future queries.
• Pagination can finally be standardized!

I tend to come at these things from the perspective of a frequent user of APIs and also someone who does quite a bit of data analysis and visualization. As such, I’m intrigued by potential of this new, dedicated verb, especially since it allows more improved query flexibility.

The ability to use structured query bodies will mean we can craft more expressive queries. This is especially useful when working with nested data structures or complex logical conditions difficult to represent in URL parameters. The QUERY method enhances semantic clarity by clearly indicating that the operation is intended for data retrieval, which may help us maintain and document data analysis workflows.

Baking in automatic retries and caching can help remove a ton of boilerplate code. Since this is more data-focused than the other verbs, we may be able to take advantage of results caching, enabling servers to cache and reuse query results for identical queries and allowing clients to cache responses.

QUERY may also help provide more API consistency across different platforms, simplifying the process of interacting with various data sources. It may also help reduce the learning curve when working with new APIs.

I’m definitely keeping an eye on this RFC and will provide updates as it progresses through the IETF processes.

hr

(This is a ridiculously short section.)

The hr (pure Bash) utility a simple yet effective tool for improving terminal readability and organization. It just draws a line based upon character patterns you supply, and is named after the same-named HTML tag. Now you can easily separate terminal output, which can be helpful in debugging issues.

reachable

Reachable is a command-line interface (CLI) tool designed to check if a domain is up or down. The basic syntax is:

$ reachable [command] [--flags]

But, you really will only care about the --timeout duration flag (does what it says on the tin) and the check subcommand.

If you want to see what it is checking for, you can tap into the --verbose flag:

$ reachable check rud.is --verbose
1.726834854672408e+09   debug   checking domain {"domain": "rud.is"}
1.7268348549349818e+09  debug   Reachable!      {"domain": "rud.is"}
+--------+-------------+------------+----------------+---------------+-------------------+------------------+------------+
| Domain | Status Code | DNS Lookup | TCP Connection | TLS Handshake | Server Processing | Content Transfer | Total Time |
+--------+-------------+------------+----------------+---------------+-------------------+------------------+------------+
|        | 200         | 2ms        | 47ms           | 51ms          | 34.257ms          |    0 ms          |  135 ms    |
+--------+-------------+------------+----------------+---------------+-------------------+------------------+------------+

You can also check more than one resource at a time:

$ reachable check rud.is hrbrmstr.dev hrbrmstr.app
+--------+-------------+------------+----------------+---------------+-------------------+------------------+------------+
| Domain | Status Code | DNS Lookup | TCP Connection | TLS Handshake | Server Processing | Content Transfer | Total Time |
+--------+-------------+------------+----------------+---------------+-------------------+------------------+------------+
|        | 403         | 1ms        | 29ms           | 63ms          | 22.108ms          |    0 ms          |  115 ms    |
|        | 200         | 2ms        | 31ms           | 57ms          | 25.898ms          |    2 ms          |  118 ms    |
|        | 200         | 3ms        | 61ms           | 64ms          | 57.308ms          |    0 ms          |  185 ms    |
+--------+-------------+------------+----------------+---------------+-------------------+------------------+------------+

I recommend installing it via:

$ go install github.com/italolelis/reachable@latest

vs. Homebrew if you’re on macOS.

FIN

Remember, you can follow and interact with the full text of The Daily Drop’s free posts on Mastodon via @dailydrop.hrbrmstr.dev@dailydrop.hrbrmstr.dev ☮️