Add HTTP database function Improvements (#1097)

src/content/doc-surrealdb/integration/http.mdx

@@ -12,9 +12,11 @@ import Label from "@components/shared/Label.astro";
 
 # HTTP & Rest
 
-The HTTP endpoints exposed by SurrealDB instances provide a simple way to interact with the database over a traditional RESTful interface. This includes selecting and modifying one or more records, executing custom SurrealQL queries, and managing SurrealML models. The endpoints are designed to be simple and easy to use in stateless environments, making them ideal for lightweight applications where a persistent database connection is not required.
+The HTTP endpoints exposed by SurrealDB instances provide a simple way to interact with the database over a traditional RESTful interface. This includes selecting and modifying one or more records, executing custom SurrealQL queries, and managing SurrealML models. 
 
-## Getting started via Postman
+The endpoints are designed to be simple and easy to use in stateless environments, making them ideal for lightweight applications where a persistent database connection is not required.
+
+## Querying via Postman
 
 The most convenient way to access these endpoints is via SurrealDB's Postman Collection. To do so, follow these steps:
 
@@ -27,6 +29,7 @@ The most convenient way to access these endpoints is via SurrealDB's Postman Col
 > [!IMPORTANT]
 > Ensure that your URL is set correctly, if running locally, the URL should be `http://localhost:8000`.By default, the URL is set to local. Start your server using the [`surreal start`](/docs/surrealdb/cli/start) command in the CLI or through Surrealist's [local database serving](/docs/surrealist/concepts/local-database-serving) functionality, before querying the endpoints.
 
+
 ## Supported methods
 
 You can use the HTTP endpoints to perform the following actions:
@@ -308,16 +311,24 @@ This HTTP RESTful endpoint imports a set of SurrealQL queries into a specific Na
 
 
 <Tabs groupId="http-sql">
-
 <TabItem value="V1" label="V1.x">
 ```bash title="Request"
-curl -X POST -u "root:root" -H "ns: mynamespace" -H "db: mydatabase" -H "Accept: application/json" -d path/to/file.surql http://localhost:8000/import
+curl -X POST -u "root:root" \
+  -H "ns: mynamespace" \
+  -H "db: mydatabase" \
+  -H "Accept: application/json" \
+  -d path/to/file.surql \
+  http://localhost:8000/import
 ```
 </TabItem>
-
 <TabItem value="V2" label="V2.x" default>
 ```bash title="Request"
-curl -X POST -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -d path/to/file.surql http://localhost:8000/import
+curl -X POST -u "root:root" \
+  -H "surreal-ns: mynamespace" \
+  -H "surreal-db: mydatabase" \
+  -H "Accept: application/json" \
+  -d path/to/file.surql \
+  http://localhost:8000/import
 ```
 </TabItem>
 
@@ -425,13 +436,25 @@ This HTTP RESTful endpoint exports all data for a specific Namespace and Databas
 
 <TabItem value="V1" label="V1.x">
 ```bash title="Request"
-curl -X GET -u "root:root" -H "ns: mynamespace" -H "db: mydatabase" -H "Accept: application/json" -o path/to/file.surql http://localhost:8000/export
+curl -X GET \
+  -u "root:root" \
+  -H "ns: mynamespace" \
+  -H "db: mydatabase" \
+  -H "Accept: application/json" \
+  -o path/to/file.surql \
+  http://localhost:8000/export
 ```
 </TabItem>
 
 <TabItem value="V2" label="V2.x" default>
 ```bash title="Request"
-curl -X GET -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -o path/to/file.surql http://localhost:8000/export
+curl -X GET \
+  -u "root:root" \
+  -H "surreal-ns: mynamespace" \
+  -H "surreal-db: mydatabase" \
+  -H "Accept: application/json" \
+  -o path/to/file.surql \
+  http://localhost:8000/export
 ```
 </TabItem>
 
@@ -2131,7 +2154,21 @@ The GraphQL endpoint enables use of GraphQL queries to interact with your data.
 
 <TabItem value="V2" label="V2.x" default>
 ```bash title="Request"
-curl -X POST -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -d '{"query": "{ person(filter: {age: {age_gt: 18}}) { id name age } }"}' http://localhost:8000/graphql
+curl -X POST \
+  -u "root:root" \
+  -H "surreal-ns: mynamespace" \
+  -H "surreal-db: mydatabase" \
+  -H "Accept: application/json" \
+  -d '{
+    "query": "{ 
+      person(filter: {age: {age_gt: 18}}) {
+        id
+        name
+        age
+      }
+    }"
+  }' \
+  http://localhost:8000/graphql
 ```
 </TabItem>
 
@@ -2259,13 +2296,25 @@ This HTTP RESTful endpoint imports a SurrealML machine learning model into a spe
 
 <TabItem value="V1" label="V1.x">
 ```bash title="Request"
-curl -X POST -u "root:root" -H "ns: mynamespace" -H "db: mydatabase" -H "Accept: application/json" -d path/to/file.surml http://localhost:8000/ml/import
+curl -X POST \
+  -u "root:root" \
+  -H "ns: mynamespace" \
+  -H "db: mydatabase" \
+  -H "Accept: application/json" \
+  -d path/to/file.surml \
+  http://localhost:8000/ml/import
 ```
 </TabItem>
 
 <TabItem value="V2" label="V2.x" default>
 ```bash title="Request"
-curl -X POST -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -d path/to/file.surml http://localhost:8000/ml/import
+curl -X POST \
+  -u "root:root" \
+  -H "surreal-ns: mynamespace" \
+  -H "surreal-db: mydatabase" \
+  -H "Accept: application/json" \
+  -d path/to/file.surml \
+  http://localhost:8000/ml/import
 ```
 </TabItem>
 
@@ -2384,13 +2433,25 @@ This HTTP RESTful endpoint exports a SurrealML machine learning model from a spe
 
 <TabItem value="V1" label="V1.x">
 ```bash title="Request"
-curl -X GET -u "root:root" -H "ns: mynamespace" -H "db: mydatabase" -H "Accept: application/json" -o path/to/file.surml http://localhost:8000/ml/export/prediction/1.0.0
+curl -X GET \
+  -u "root:root" \
+  -H "ns: mynamespace" \
+  -H "db: mydatabase" \
+  -H "Accept: application/json" \
+  -o path/to/file.surml \
+  http://localhost:8000/ml/export/prediction/1.0.0
 ```
 </TabItem>
 
 <TabItem value="V2" label="V2.x" default>
 ```bash title="Request"
-curl -X GET -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -o path/to/file.surml http://localhost:8000/ml/export/prediction/1.0.0
+curl -X GET \
+  -u "root:root" \
+  -H "surreal-ns: mynamespace" \
+  -H "surreal-db: mydatabase" \
+  -H "Accept: application/json" \
+  -o path/to/file.surml \
+  http://localhost:8000/ml/export/prediction/1.0.0
 ```
 </TabItem>
 

src/content/doc-surrealql/functions/database/http.mdx

@@ -4,6 +4,7 @@ sidebar_label: HTTP functions
 title: HTTP functions | SurrealQL
 description: These functions can be used when opening and submitting remote web requests, and webhooks.
 ---
+import Since from '@components/shared/Since.astro';
 
 # HTTP functions
 
@@ -44,6 +45,22 @@ These functions can be used when opening and submitting remote web requests, and
   </tbody>
 </table>
 
+
+## Before you begin
+
+<Since v="v2.2.0" />
+
+From version `2.2` of SurrealDB, the HTTP functions have been improved to provide a more consistent and user-friendly experience. These improvements include:
+
+- **Enhanced HTTP error messages**: The server provides more descriptive error responses, including relevant HTTP status codes and detailed error information when available.
+
+- **Raw SurrealQL data encoding**: Data types are preserved more faithfully in responses through improved encoding.
+  - SurrealQL **byte values** are now sent as raw bytes (not base64-encoded or JSON-encoded).  
+  - SurrealQL **string values** are sent as raw strings.  
+  - All other SurrealQL values (numbers, arrays, objects, booleans, etc.) are automatically JSON-encoded.
+
+- **Manual Header Configuration**: SurrealDB no longer automatically adds `Content-Type: application/octet-stream` to responses when the body contains SurrealQL byte values. If you need this header, you can set it manually.
+
 ## `http::head`
 
 The `http::head` function performs a remote HTTP `HEAD` request. The first parameter is the URL of the remote endpoint. If the response does not return a `2XX` status code, then the function will fail and return the error.
@@ -79,7 +96,9 @@ null
 
 ## `http::get`
 
-The `http::get` function performs a remote HTTP GET request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an `application/json content-type`, then the response is parsed and returned as a value, otherwise the response is treated as text.
+The `http::get` function performs a remote HTTP `GET` request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error. 
+
+If the remote endpoint returns an `application/json content-type`, then the response is parsed and returned as a value, otherwise the response is treated as text.
 
 ```surql title="API DEFINITION"
 http::get(string) -> value
@@ -117,15 +136,15 @@ The `http::put` function performs a remote HTTP `PUT` request. The first paramet
 ```surql title="API DEFINITION"
 http::put(string, object) -> value
 ```
-If an object is given as the second argument, then this can be used to set the request headers.
+If an object is given as the third argument, then this can be used to set the request headers.
 
 ```surql title="API DEFINITION"
 http::put(string, object, object) -> value
 ```
 
 The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealql/statements/return) statement:
 
-```surql
+```surql title="Request without headers"
 RETURN http::put('https://dummyjson.com/comments', {
   "id": 1,
   "body": "This is some awesome thinking!",
@@ -135,8 +154,25 @@ RETURN http::put('https://dummyjson.com/comments', {
     "username": "eburras1q"
   }
 });
+```
 
+```surql title="Request with headers"
+RETURN http::put('https://dummyjson.com/comments', {
+  "id": 1,
+  "body": "This is some awesome thinking!",
+  "postId": 100,
+  "user": {
+    "id": 63,
+    "username": "eburras1q"
+  }
+}, {
+  'Authorization': 'Bearer your-token-here',
+  'Content-Type': 'application/json',
+  'x-custom-header': 'custom-value'
+});
+```
 
+```surql title="Response"
 {
   "id": 1,
   "body": "This is some awesome thinking!",
@@ -157,15 +193,15 @@ The `http::post` function performs a remote HTTP `POST` request. The first param
 ```surql title="API DEFINITION"
 http::post(string, object) -> value
 ```
-If an object is given as the second argument, then this can be used to set the request headers.
+If an object is given as the third argument, then this can be used to set the request headers.
 
 ```surql title="API DEFINITION"
 http::post(string, object, object) -> value
 ```
 
 The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealql/statements/return) statement:
 
-```surql
+```surql title="Request without headers"
 RETURN http::post('https://dummyjson.com/comments/1', {
   "id": 1,
   "body": "This is some awesome thinking!",
@@ -175,8 +211,25 @@ RETURN http::post('https://dummyjson.com/comments/1', {
     "username": "eburras1q"
   }
 });
+```
 
+```surql title="Request with headers"
+RETURN http::post('https://dummyjson.com/comments/1', {
+  "id": 1,
+  "body": "This is some awesome thinking!",
+  "postId": 100,
+  "user": {
+    "id": 63,
+    "username": "eburras1q"
+  }
+}, {
+  'Authorization': 'Bearer your-token-here',
+  'Content-Type': 'application/json',
+  'x-custom-header': 'custom-value'
+});
+```
 
+```surql title="Response"
 {
   "id": 1,
   "body": "This is some awesome thinking!",
@@ -197,15 +250,15 @@ The `http::patch` function performs a remote HTTP `PATCH` request. The first par
 ```surql title="API DEFINITION"
 http::patch(string, object) -> value
 ```
-If an object is given as the second argument, then this can be used to set the request headers.
+If an object is given as the third argument, then this can be used to set the request headers.
 
 ```surql title="API DEFINITION"
 http::patch(string, object, object) -> value
 ```
 
 The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealql/statements/return) statement:
 
-```surql
+```surql title="Request without headers"
 RETURN http::patch('https://dummyjson.com/comments/1', {
   "id": 1,
   "body": "This is some awesome thinking!",
@@ -215,8 +268,25 @@ RETURN http::patch('https://dummyjson.com/comments/1', {
     "username": "eburras1q"
   }
 });
+```
 
+```surql title="Setting the request headers"
+RETURN http::patch('https://dummyjson.com/comments/1', {
+  "id": 1,
+  "body": "This is some awesome thinking!",
+  "postId": 100,
+  "user": {
+    "id": 63,
+    "username": "eburras1q"
+  }
+}, {
+  'Authorization': 'Bearer your-token-here',
+  'Content-Type': 'application/json',
+  'x-custom-header': 'custom-value'
+});
+```
 
+```surql title="RESPONSE"
 {
   "id": 1,
   "body": "This is some awesome thinking!",