HTTP QUERY Method

package main

import (
  "bytes"
  "encoding/json"
  "net/http"
)

func queryUsers(client *http.Client, baseURL string) (*http.Response, error) {
  body, _ := json.Marshal(map[string]interface{}{
    "filter": map[string]interface{}{
      "status": "active",
      "dept":   []string{"Engineering"},
    },
    "sort":  []map[string]string{{"field": "name", "dir": "asc"}},
    "limit": 50,
  })

  req, _ := http.NewRequest("QUERY", baseURL+"/users", bytes.NewReader(body))
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("Accept", "application/json")

  // QUERY is safe + idempotent — the client can retry on timeout
  return client.Do(req)
}

// Server handler (uses pkg/query from this project)
import "github.com/jralmaraz/http-query-method/pkg/query"

handler := query.JSONQueryHandler(func(q map[string]interface{}) (interface{}, error) {
  results := db.Query(q["filter"], q["sort"], q["limit"])
  return map[string]interface{}{"results": results}, nil
})

// ─── Browser / Node.js (fetch API) ───────────────────────────────
const response = await fetch('https://api.example.com/users', {
  method: 'QUERY',         // RFC 10008 method
  headers: {
    'Content-Type': 'application/json',
    'Accept':       'application/json',
  },
  body: JSON.stringify({
    filter: { status: 'active', dept: ['Engineering'] },
    sort:   [{ field: 'name', dir: 'asc' }],
    limit:  50,
  }),
  // Note: QUERY is not a CORS-safelisted method — preflight will fire
});

const data = await response.json();
console.log(`Cache: ${response.headers.get('X-Cache')}`);      // MISS or HIT
console.log(`Results URI: ${response.headers.get('Content-Location')}`);

// ─── Node.js with undici (explicit QUERY support) ─────────────────
import { fetch } from 'undici';   // undici allows custom methods
const res = await fetch(url, { method: 'QUERY', body, headers });

import httpx  # httpx supports custom methods natively

query_body = {
    "filter": {"status": "active", "dept": ["Engineering"]},
    "sort":   [{"field": "name", "dir": "asc"}],
    "limit": 50,
}

# httpx allows any HTTP method string
response = httpx.request(
    method="QUERY",
    url="https://api.example.com/users",
    json=query_body,
    headers={"Accept": "application/json"},
)

data = response.json()
print(f"Cache: {response.headers.get('X-Cache')}")          # MISS or HIT
print(f"Results: {data['results']}")

# Flask server handler
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/users', methods=['QUERY'])
def query_users():
    query = request.get_json()
    if not query:
        return jsonify(error="Content-Type required"), 400
    results = db.search(query["filter"], query.get("limit", 20))
    return jsonify(results=results)

import java.net.URI;
import java.net.http.*;
import java.net.URLEncoder;

// ─── GET (query in URI — breaks at ~2000 chars) ───────────────────
var client = HttpClient.newHttpClient();
var params = URLEncoder.encode("""
    {"status":"active","dept":["Engineering"]}""", StandardCharsets.UTF_8);
var get = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/users?filter=" + params + "&limit=50"))
    .GET()
    .header("Accept", "application/json")
    .build();

// ─── POST (not safe, not cacheable) ───────────────────────────────
var body = """
    {"filter":{"status":"active","dept":["Engineering"]},
     "sort":[{"field":"name","dir":"asc"}],"limit":50}""";
var post = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/users/search"))
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .header("Content-Type", "application/json")
    .build();

// ─── QUERY (safe + cacheable + body) — Java 11+ HttpClient ────────
var query = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/users"))
    .method("QUERY", HttpRequest.BodyPublishers.ofString(body))
    .headers("Content-Type", "application/json",
             "Accept",       "application/json")
    .build();
var response = client.send(query, HttpResponse.BodyHandlers.ofString());
// QUERY is safe + idempotent → safe to retry on timeout or 5xx

// ─── Spring Boot 6 client (RestClient with custom method) ─────────
@Service
public class UserQueryService {
    private final RestClient rest = RestClient.create();

    public List<User> findUsers(UserFilter filter) {
        return rest
            .method(HttpMethod.valueOf("QUERY"))
            .uri("https://api.example.com/users")
            .contentType(MediaType.APPLICATION_JSON)
            .body(filter)
            .retrieve()
            .body(new ParameterizedTypeReference<List<User>>() {});
    }
}

// ─── Spring Boot 6 handler (server side) ──────────────────────────
@RestController
@RequestMapping("/users")
public class UserController {

    @RequestMapping(method = RequestMethod.valueOf("QUERY"),
                    consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<List<User>> queryUsers(@RequestBody UserFilter filter) {
        var results = userService.search(filter);
        return ResponseEntity.ok()
            .header("Content-Location", "/users/results/" + filter.cacheKey())
            .body(results);
    }
}

use reqwest::Method;

// reqwest supports custom methods via Method::from_bytes
let query_method = Method::from_bytes(b"QUERY").unwrap();

let body = serde_json::json!({
    "filter": {"status": "active", "dept": ["Engineering"]},
    "sort":   [{"field": "name", "dir": "asc"}],
    "limit": 50,
});

let response = client
    .request(query_method, "https://api.example.com/users")
    .header("Content-Type", "application/json")
    .header("Accept",       "application/json")
    .json(&body)
    .send()
    .await?;

// Axum server handler
use axum::{routing::method_routing, Router, Json, http::StatusCode};

async fn query_users(Json(q): Json<serde_json::Value>) -> Json<serde_json::Value> {
    let results = db.search(&q).await;
    Json(serde_json::json!({"results": results}))
}

let app = Router::new()
    .route("/users", method_routing::on(MethodFilter::try_from("QUERY").unwrap(), query_users));

# nginx — cache QUERY responses using body hash as key
http {
  proxy_cache_path /var/cache/nginx/query levels=1:2
                   keys_zone=query_cache:10m max_size=1g
                   inactive=5m use_temp_path=off;

  server {
    location /api/ {
      # Allow QUERY to be cached (nginx treats unknown methods as uncacheable by default)
      proxy_cache_methods GET HEAD QUERY;
      proxy_cache query_cache;

      # Cache key: URI + body digest (requires request body digest module)
      proxy_cache_key "$scheme$request_method$host$request_uri$http_content_type$request_body_hash";

      proxy_cache_valid 200 5m;
      add_header X-Cache $upstream_cache_status;

      proxy_pass http://backend;
    }
  }
}

// Apache Tomcat 12 + Servlet 6.1 — native QUERY method support
// apache/tomcat#1026 merged July 1 2026; requires Tomcat 12.0.x + Servlet 6.1 API
// Tomcat 12 is the FIRST Java servlet container to ship native doQuery() dispatch.

import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.*;
import java.io.IOException;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.concurrent.ConcurrentHashMap;

@WebServlet("/api/users")
public class UserQueryServlet extends HttpServlet {

    // Simple in-process cache — replace with Ehcache / Caffeine in production
    private final ConcurrentHashMap<String, byte[]> cache = new ConcurrentHashMap<>();

    // Tomcat 12 dispatches QUERY to doQuery() — override like doGet() / doPost()
    @Override
    protected void doQuery(HttpServletRequest req, HttpServletResponse resp)
            throws IOException {

        String ct = req.getContentType();
        if (ct == null || !ct.contains("application/json")) {
            resp.setStatus(415);
            resp.setHeader("Accept-Query", "application/json"); // RFC 10008 §3
            return;
        }

        byte[] body = req.getInputStream().readAllBytes();

        // RFC 10008 §2.2 — body-keyed cache key (SHA-256 of URI + CT + body)
        String cacheKey = sha256Hex(
            (req.getRequestURI() + "\0" + ct + "\0").getBytes() ,body);

        byte[] cached = cache.get(cacheKey);
        if (cached != null) {
            resp.setContentType("application/json");
            resp.setHeader("X-Cache", "HIT");
            resp.getOutputStream().write(cached);
            return;
        }

        // QUERY is safe + idempotent → no side effects; safe to retry
        byte[] result = userRepository.search(body);
        cache.put(cacheKey, result);

        resp.setStatus(200);
        resp.setContentType("application/json");
        resp.setHeader("Cache-Control", "max-age=300");
        resp.setHeader("Content-Location", "/api/users/results/" + cacheKey); // RFC 10008 §4
        resp.setHeader("X-Cache", "MISS");
        resp.getOutputStream().write(result);
    }

    private String sha256Hex(byte[]... parts) throws IOException {
        try {
            var md = MessageDigest.getInstance("SHA-256");
            for (var p : parts) md.update(p);
            return HexFormat.of().formatHex(md.digest());
        } catch (Exception e) { throw new IOException(e); }
    }
}

// Spring Boot 6 — QUERY caching handler
// Spring Framework issue #36988 closed as "not planned" — @QueryMapping annotation
// cannot be added because @QueryMapping is already claimed by Spring GraphQL.
// Community-endorsed workaround (confirmed by Spring team): RequestMethod.valueOf("QUERY")
// This matches how @RequestMapping resolves any custom HTTP method name.

@RestController
@RequestMapping("/api/users")
public class UserQueryController {

    private final UserService userService;
    private final Cache<String, List<User>> queryCache;  // Caffeine / Ehcache

    // No @QueryMapping — use RequestMethod.valueOf("QUERY") workaround
    @RequestMapping(method = RequestMethod.valueOf("QUERY"),
                    consumes = MediaType.APPLICATION_JSON_VALUE,
                    produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<List<User>> queryUsers(@RequestBody UserFilter filter) {

        // RFC 10008 §2.2 — body-keyed cache: use deterministic filter key
        String cacheKey = filter.cacheKey();  // SHA-256(canonical JSON) of filter

        List<User> cached = queryCache.getIfPresent(cacheKey);
        if (cached != null) {
            return ResponseEntity.ok()
                .header("X-Cache", "HIT")
                .header("Content-Location", "/api/users/results/" + cacheKey)
                .body(cached);
        }

        // QUERY is idempotent — safe to run under Spring's @Cacheable as well
        List<User> results = userService.search(filter);
        queryCache.put(cacheKey, results);

        return ResponseEntity.ok()
            .header("Cache-Control", "max-age=300")
            .header("Content-Location", "/api/users/results/" + cacheKey) // RFC 10008 §4
            .header("X-Cache", "MISS")
            .body(results);
    }
}

// RestClient (Spring 6.1+) on the calling side — no special setup needed
var results = RestClient.create()
    .method(HttpMethod.valueOf("QUERY"))
    .uri("https://api.example.com/api/users")
    .contentType(MediaType.APPLICATION_JSON)
    .body(filter)
    .retrieve()
    .body(new ParameterizedTypeReference<List<User>>() {});

// Varnish VCL — full QUERY caching with body-keyed lookup
import digest;

sub vcl_recv {
  // Allow QUERY to pass through cache lookup (not just GET/HEAD)
  if (req.method == "QUERY") {
    // Buffer the body (requires bereq.body access in VCL 7+)
    set req.http.X-Query-Body-Hash =
      digest.hash_sha256(req.body);

    // Synthesise a cache-lookup key combining URI + body hash
    set req.http.X-Cache-Key =
      req.url + "|" + req.http.Content-Type + "|" + req.http.X-Query-Body-Hash;

    return(hash);   // proceed to cache lookup
  }
}

sub vcl_hash {
  if (req.method == "QUERY") {
    hash_data(req.http.X-Cache-Key);
    return(lookup);
  }
}

sub vcl_deliver {
  set resp.http.X-Cache = if(obj.hits > 0, "HIT", "MISS");
}

const express = require('express');
const app = express();

// Express doesn't know QUERY natively — register it explicitly
app.all('/users', (req, res) => {
  if (req.method !== 'QUERY') {
    return res.set('Allow', 'QUERY').status(405).json({ error: 'Method Not Allowed' });
  }

  // RFC 10008 §2: validate Content-Type
  const ct = req.headers['content-type'] || '';
  if (!ct) {
    return res.status(400).json({ error: 'Content-Type is required for QUERY' });
  }
  if (!ct.includes('application/json')) {
    return res
      .set('Accept-Query', 'application/json')    // RFC 10008 §3
      .status(415).json({ error: 'Unsupported format' });
  }

  const results = db.search(req.body);
  res.json({ results });
});

from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute

app = FastAPI()

# FastAPI allows custom HTTP methods via include_router
@app.api_route("/users", methods=["QUERY"])
async def query_users(request: Request):
    ct = request.headers.get("content-type", "")
    if not ct:
        return Response(
            content='{"error":"Content-Type required"}',
            status_code=400, media_type="application/json"
        )
    if "application/json" not in ct:
        return Response(
            content='{"error":"Unsupported format"}',
            status_code=415, media_type="application/json",
            headers={"Accept-Query": "application/json"}   # RFC 10008 §3
        )
    body = await request.json()
    results = db.search(body)
    return {"results": results}

import org.springframework.web.bind.annotation.*;
import org.springframework.http.*;

@RestController
@RequestMapping("/users")
public class UserController {

    // Register QUERY method — Spring MVC accepts arbitrary method names
    @RequestMapping(method = RequestMethod.valueOf("QUERY"),
                    consumes = MediaType.APPLICATION_JSON_VALUE,
                    produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<?> queryUsers(
            HttpServletRequest req,
            @RequestBody(required = false) UserFilter filter) {

        // 400 — missing Content-Type or body (Spring throws HttpMediaTypeNotSupportedException)
        if (filter == null) {
            return ResponseEntity.badRequest()
                .body(Map.of("error", "Content-Type and body required"));
        }

        // Business logic — safe to retry (QUERY is idempotent)
        var results = userService.search(filter);

        // 200 — include Content-Location for the result URI (RFC 10008 §4)
        return ResponseEntity.ok()
            .header("Content-Location", "/users/results/" + filter.cacheKey())
            .body(results);
    }

    // 415 — wrong Content-Type; Spring auto-sends this but you can customise:
    @ExceptionHandler(HttpMediaTypeNotSupportedException.class)
    public ResponseEntity<?> handleUnsupportedMedia() {
        return ResponseEntity.status(415)
            .header("Accept-Query", "application/json")  // RFC 10008 §3
            .body(Map.of("error", "Unsupported format; use application/json"));
    }

    // 405 — if someone sends GET or POST to this endpoint
    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
    public ResponseEntity<?> handleWrongMethod() {
        return ResponseEntity.status(405)
            .header("Allow", "QUERY, OPTIONS")
            .body(Map.of("error", "Use QUERY method for search operations"));
    }
}

// GraphQL: accept application/graphql body
import "github.com/graphql-go/graphql"

handler := query.NewHandler(func(req *query.Request) ([]byte, string, error) {
  // Accept both pure GraphQL body and JSON-wrapped {query, variables}
  var gqlQuery string
  var variables map[string]interface{}

  if strings.HasPrefix(req.ContentType, "application/graphql") {
    gqlQuery = string(req.Body)
  } else {
    var envelope struct { Query string; Variables map[string]interface{} }
    json.Unmarshal(req.Body, &envelope)
    gqlQuery = envelope.Query
    variables = envelope.Variables
  }

  result := graphql.Do(graphql.Params{Schema: schema, RequestString: gqlQuery, VariableValues: variables})
  out, _ := json.Marshal(result)
  return out, "application/json", nil
}, "application/graphql", "application/json")

from fastapi import FastAPI, Request, Response
from sqlalchemy import text
import json

app = FastAPI()

@app.api_route("/data", methods=["QUERY"])
async def sql_query(request: Request):
    ct = request.headers.get("content-type", "")

    if "application/sql" not in ct:
        return Response(status_code=415,
                        headers={"Accept-Query": "application/sql, application/json"})

    sql = (await request.body()).decode()

    # Enforce read-only: parse AST, reject non-SELECT
    if not sql.strip().upper().startswith("SELECT"):
        return Response(status_code=422,
                        content='{"error":"Only SELECT allowed"}')

    with db.connect() as conn:
        result = conn.execute(text(sql))
        rows = [dict(r) for r in result]

    return {"results": rows, "total": len(rows)}

const express = require('express');
const { MongoClient } = require('mongodb');

app.all('/documents', async (req, res) => {
  if (req.method !== 'QUERY') return res.status(405).send();

  const filter  = req.body?.filter  || {};
  const project = req.body?.project || {};
  const sort    = req.body?.sort    || {};
  const limit   = Math.min(req.body?.limit || 100, 1000);

  // MongoDB filter expression is the QUERY body — no separate query param
  const results = await collection
    .find(filter, { projection: project })
    .sort(sort)
    .limit(limit)
    .toArray();

  // Return Content-Location for client-side bookmarking
  const queryHash = sha256(JSON.stringify(req.body));
  res
    .set('Content-Location', `/queries/${queryHash}`)
    .set('Cache-Control', 'max-age=300')
    .json({ results, total: results.length });
});