# http-query
[](https://crates.io/crates/http-query)
[](https://docs.rs/http-query)
[](https://github.com/thatwasyahya/http-query/actions/workflows/ci.yml)
[](LICENSE)
A client and server SDK for the **HTTP `QUERY` method** ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008.html)) in Rust.
`QUERY` is a **safe** and **idempotent** request method that carries a request
body describing a query to run against the target resource. It combines the
best of `GET` (safe, cacheable, retryable) and `POST` (arbitrary request body):
the query travels in the body instead of the URI.
```toml
[dependencies]
http-query = "0.1"
```
## Sending a query
The async client is built on [`reqwest`](https://crates.io/crates/reqwest)
(the `client` feature, enabled by default).
```rust,no_run
use http_query::Client;
# async fn run() -> Result<(), http_query::Error> {
let client = Client::new();
// Raw body + content type
let resp = client
.query_string("https://example.org/search", "application/sql", "SELECT 1")
.await?;
// JSON in, JSON out (validates the status)
#[derive(serde::Serialize)]
struct Search<'a> { q: &'a str }
#[derive(serde::Deserialize)]
struct Results { hits: u32 }
let results: Results = client
.query_json_into("https://example.org/search", &Search { q: "rust" })
.await?;
# let _ = resp; let _ = results.hits; Ok(()) }
```
## Result vs. equivalent resource
A `QUERY` response can advertise two **distinct** `GET`-retrievable URIs
([RFC 10008 §2.3–2.4](https://www.rfc-editor.org/rfc/rfc10008.html#section-2.3)):
- **`Content-Location`** — the *stored result* of the query just run.
`Client::fetch_result` follows it.
- **`Location`** — the *equivalent resource*, whose `GET` **re-runs** the query.
`Client::fetch_equivalent` follows it.
## Discovering support
`Accept-Query` is an [RFC 9651](https://www.rfc-editor.org/rfc/rfc9651.html)
Structured Fields List; it is parsed and serialized correctly (quoted strings,
parameters, `*/*` and `type/*` wildcards).
```rust,no_run
# async fn run() -> Result<(), http_query::Error> {
# let client = http_query::Client::new();
let discovery = client.options("https://example.org/search").await?;
if discovery.supports_query {
println!("accepted formats: {:?}", discovery.accept_query);
}
# Ok(()) }
```
## Redirects
QUERY redirects are handled per [RFC 10008 §2.5](https://www.rfc-editor.org/rfc/rfc10008.html#section-2.5):
`301`/`302`/`307`/`308` re-issue the QUERY with its body, while only `303`
switches to `GET`. `Client::new` disables reqwest's own redirect following so
the SDK can apply these rules (the transport default would downgrade `301`/`302`
to `GET` and drop the body). Configure the limit with `with_max_redirects`;
exceeding it returns `Error::TooManyRedirects`.
## Serving QUERY
The [`http_query::server`] helpers are framework-agnostic (they work on
`http::HeaderMap` and a method string), so they plug into axum, hyper, actix,
etc. They enforce the RFC's rules: `400` for a missing `Content-Type`, `415`
for an unsupported query media type, `405` for non-QUERY methods.
```rust,no_run
use http_query::server::{check_query_request, QueryRejection};
# use http::HeaderMap;
# fn handle(method: &str, headers: &HeaderMap) {
match check_query_request(method, headers, &["application/json"]) {
Ok(()) => { /* evaluate the query in the request body */ }
Err(rejection) => { /* respond with rejection.status() */ }
}
# }
```
See [`examples/axum_server.rs`](examples/axum_server.rs) for a complete server.
## Caching
Unlike `GET`, a QUERY cache entry must be keyed on the request body:
```rust
let key = http_query::cache_key(
"https://example.org/search",
http_query::MEDIA_TYPE_JSON,
br#"{"q":"rust"}"#,
);
# assert_eq!(key.len(), 64);
```
## Feature flags
- `client` *(default)* — the async `reqwest`-based [`Client`].
Disable default features for a runtime-agnostic core (Structured Fields
parsing, cache keys, response/discovery helpers, and the server helpers) with
no async or client dependency.
## License
[BSD-3-Clause](LICENSE).