From 1dbc1dfed8b26598236ff430874e634b41e21125 Mon Sep 17 00:00:00 2001
From: jeadie <jack@spice.ai>
Date: Wed, 27 Mar 2024 21:00:27 +1100
Subject: [PATCH] initial HTTP API for v1/sql

---
 spiceaidocs/docs/clients/http_api/index.md | 84 ++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 spiceaidocs/docs/clients/http_api/index.md

diff --git a/spiceaidocs/docs/clients/http_api/index.md b/spiceaidocs/docs/clients/http_api/index.md
new file mode 100644
index 00000000..c9ca90d9
--- /dev/null
+++ b/spiceaidocs/docs/clients/http_api/index.md
@@ -0,0 +1,84 @@
+---
+title: "HTTP API"
+sidebar_label: "HTTP"
+description: 'Directly call the Spice runtime via HTTP requests'
+---
+
+The Spice runtime supports SQL queries directly from HTTP requests. 
+
+An example CuRL
+```shell
+curl -XPOST "127.0.0.1:3000/v1/sql" \
+     --data "SELECT avg(total_amount), \
+                    avg(tip_amount), \
+                    count(1), \
+                    passenger_count \
+              FROM my_table \
+              GROUP BY passenger_count \
+              ORDER BY passenger_count ASC \
+              LIMIT 3"
+```
+And response
+```json
+[
+    {
+        "AVG(my_table.tip_amount)": 3.072259971396793,
+        "AVG(my_table.total_amount)": 25.327816939456525,
+        "COUNT(Int64(1))": 31465,
+        "passenger_count": 0
+    },
+    {
+        "AVG(my_table.tip_amount)": 3.3712622884680057,
+        "AVG(my_table.total_amount)": 26.205230445474996,
+        "COUNT(Int64(1))": 2188739,
+        "passenger_count": 1
+    },
+    {
+        "AVG(my_table.tip_amount)": 3.7171302113290854,
+        "AVG(my_table.total_amount)": 29.520659930930304,
+        "COUNT(Int64(1))": 405103,
+        "passenger_count": 2
+    }
+]
+```
+This allows for simple integrating into any language or framework 
+<Tabs>
+  <TabItem value="python" label="Python" default>
+    ```python
+    from typing import Optional
+    import requests
+    import pandas as pd
+
+    def query_runtime(query: str, url: str =  "http://127.0.0.1:3000") -> Optional[pd.DataFrame]:
+        response = requests.post(url, data=query)
+        
+        if response.status_code != 200:
+            print(f"Error: Received status code {response.status_code}")
+            return None
+        
+        return pd.DataFrame(response.json())
+    ```
+  </TabItem>
+  <TabItem value="javascript" label="Javascript">
+    ```javascript
+    async function queryRuntime(query, url = "http://127.0.0.1:3000") {
+        try {
+            const response = await fetch(url, {method: 'POST', body: query});
+            if (!response.ok) {
+            console.error(`Error: Received status code ${response.status}`);
+            return null;
+            }
+
+            return await response.json();
+        } catch (error) {
+            return error;
+        }
+    }
+    ```
+  </TabItem>
+  </Tabs>
+
+<!-- Goal-State/What
+HackerNews quality HTTP SQL interface docs for POST /v1/sql, including quick starts at https://docs.spiceai.org/clients/.
+
+Include sub-pages of deployments and inference, benefits, why do this, example use-cases, considerations, etc. -->
\ No newline at end of file