diff --git a/docs/en/docs/tutorial/http-query.md b/docs/en/docs/tutorial/http-query.md new file mode 100644 index 000000000..a2ed698a7 --- /dev/null +++ b/docs/en/docs/tutorial/http-query.md @@ -0,0 +1,30 @@ +# HTTP QUERY + +Typically, when you want to read data you use `GET`. If you need to send complex data (like a large JSON object) to filter that data, you traditionally had to use `POST` because `GET` requests does not support request bodies. + +However, using `POST` for read-only operations isn't semantically correct, as `POST` implies that you are creating or modifying data. + +There is a newer HTTP method called **QUERY**. It is designed exactly for this: performing safe, idempotent read operations that require a request body. + +## Using `QUERY` + +In **FastAPI**, you can use the `QUERY` method using the `@app.query()` decorator. + +It works similarly to `@app.post()`, allowing you to receive Pydantic models in the body, but it signals that the operation is a read-only query. + + +{* ../../docs_src/http_query/tutorial001.py hl[7] *} + +### Testing it + +You can test it using an HTTP client that supports the `QUERY` method. + +Because it allows a body, you can send complex filters without hitting URL length limits common with `GET` query parameters. + +### Technical Details + +The `QUERY` method is defined in the [IETF HTTP QUERY Method Draft](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-02.html). It is considered: + +* **Safe**: It does not alter the state of the server (read-only). +* **Idempotent**: Making the same request multiple times yields the same result. + diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index fd346a3d3..b549d04bd 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -136,6 +136,7 @@ nav: - tutorial/request-forms-and-files.md - tutorial/handling-errors.md - tutorial/path-operation-configuration.md + - tutorial/http-query.md - tutorial/encoder.md - tutorial/body-updates.md - Dependencies: diff --git a/docs_src/http_query/tutorial001.py b/docs_src/http_query/tutorial001.py new file mode 100644 index 000000000..2fd51acd0 --- /dev/null +++ b/docs_src/http_query/tutorial001.py @@ -0,0 +1,17 @@ +from typing import Optional + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class ItemSearch(BaseModel): + keyword: str + min_price: Optional[float] = None + max_price: Optional[float] = None + + +@app.query("/items/") +async def search_items(search_params: ItemSearch): + return {"message": "Searching items", "search_params": search_params} \ No newline at end of file diff --git a/tests/test_tutorial/test_http_query/test_tutorial001.py b/tests/test_tutorial/test_http_query/test_tutorial001.py new file mode 100644 index 000000000..5a29d2f0f --- /dev/null +++ b/tests/test_tutorial/test_http_query/test_tutorial001.py @@ -0,0 +1,32 @@ +from fastapi.testclient import TestClient + +from docs_src.http_query.tutorial001 import app + +client = TestClient(app) + + +def test_query_items(): + response = client.request( + "QUERY", + "/items/", + json={"keyword": "book", "max_price": 50}, + ) + assert response.status_code == 200 + assert response.json() == { + "message": "Searching items", + "search_params": { + "keyword": "book", + "min_price": None, + "max_price": 50.0, + }, + } + + +def test_openapi_schema(): + response = client.get("/openapi.json") + assert response.status_code == 200 + schema = response.json() + assert "query" in schema["paths"]["/items/"] + operation = schema["paths"]["/items/"]["query"] + assert "requestBody" in operation + assert "ItemSearch" in operation["requestBody"]["content"]["application/json"]["schema"]["$ref"]