From 902414cb173b5259f728ae577d12a8ff2e89c6ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Wed, 24 Jun 2026 18:53:49 +0200
Subject: [PATCH] feat(api): Add support for HTTP QUERY

---
 api/src/commonMain/kotlin/Resource.kt | 35 ++++++++++++++++++++++++++-
 docs/website/docs/endpoints.md        |  1 +
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/api/src/commonMain/kotlin/Resource.kt b/api/src/commonMain/kotlin/Resource.kt
index a252f6e..c7dc6c1 100644
--- a/api/src/commonMain/kotlin/Resource.kt
+++ b/api/src/commonMain/kotlin/Resource.kt
@@ -91,7 +91,7 @@ sealed class Resource(
 	 *
 	 * ### Properties
 	 *
-	 * - SHOULD NOT declare a [request][AnyEndpoint.Builder.request] body
+	 * - SHOULD NOT declare a [request][AnyEndpoint.Builder.request] body (use [query] instead)
 	 * - should declare a [response][AnyEndpoint.Builder.response] body
 	 * - should be [safe](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP)
 	 * - should be [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent)
@@ -119,6 +119,39 @@ sealed class Resource(
 	 */
 	protected fun get(path: String? = null) = endpoint(HttpMethod.Get, path)
 
+	/**
+	 * Creates a [`QUERY`][HttpMethod.Query] HTTP endpoint in this resource.
+	 *
+	 * `QUERY` endpoints are used to access information which requires complex data to access.
+	 * They can be thought of as `GET`-with-a-body.
+	 * They should not modify the state of any resources.
+	 *
+	 * ### Properties
+	 *
+	 * - should declare a [request][AnyEndpoint.Builder.request] body
+	 * - should declare a [response][AnyEndpoint.Builder.response] body
+	 * - should be [safe](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP)
+	 * - should be [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent)
+	 * - should be [cacheable](https://developer.mozilla.org/en-US/docs/Glossary/Cacheable)
+	 *
+	 * ### Example
+	 *
+	 * ```kotlin
+	 * object User : DynamicResource<Users>("user", parent = Users) {
+	 *
+	 *     // QUERY …/{user}/favorites
+	 *     val favorites by query("favorites")
+	 *         .request<FavoriteSearchCriteria>()
+	 *         .response<List<UserFavoriteDto>>()
+	 * }
+	 * ```
+	 *
+	 * To learn more about what can be customized on an endpoint, see [AnyEndpoint.Builder].
+	 *
+	 * Learn more about [`QUERY` (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/QUERY).
+	 */
+	protected fun query(path: String? = null) = endpoint(HttpMethod.Query, path)
+
 	/**
 	 * Creates a [`POST`][HttpMethod.Post] HTTP endpoint in this resource.
 	 *
diff --git a/docs/website/docs/endpoints.md b/docs/website/docs/endpoints.md
index 275d30f..4d49f67 100644
--- a/docs/website/docs/endpoints.md
+++ b/docs/website/docs/endpoints.md
@@ -32,6 +32,7 @@ For the remainder of this page, the enclosing resource is omitted from code samp
 An endpoint is declared using `by` followed by the name of the HTTP method. The available methods are:
 
 - `by get()`: HTTP `GET`
+- `by query()`: HTTP `QUERY`
 - `by post()`: HTTP `POST`
 - `by put()`: HTTP `PUT`
 - `by patch()`: HTTP `PATCH`
-- 
2.51.2