DEFINE API documentation (#1171)

Co-authored-by: Obinna Ekwuno <[email protected]>
surrealdb · Feb 25, 2025 · b5aa5ba · b5aa5ba
1 parent c3d674f
commit b5aa5ba
Show file tree

Hide file tree

Showing 42 changed files with 774 additions and 105 deletions.
diff --git a/src/content/doc-surrealdb/cli/env.mdx b/src/content/doc-surrealdb/cli/env.mdx
@@ -296,6 +296,12 @@ surreal start --user root --pass root
       <td scope="row" data-label="Argument">allow-all</td>
       <td scope="row" data-label="Details">Allow all capabilities.</td>
     </tr>
+    <tr>
+      <td scope="row" data-label="Env var"><code>SURREAL_CAPS_ALLOW_ARBITRARY_QUERY</code></td>
+      <td scope="row" data-label="Command">surreal start</td>
+      <td scope="row" data-label="Argument">allow-arbitrary-query</td>
+      <td scope="row" data-label="Details">Allows arbitrary queries to be used by user groups. Possible user groups are: 'guest', 'record', and 'system'.</td>
+    </tr>
     <tr>
       <td scope="row" data-label="Env var"><code>SURREAL_CAPS_ALLOW_FUNC</code></td>
       <td scope="row" data-label="Command">surreal start</td>

diff --git a/src/content/doc-surrealdb/cli/start.mdx b/src/content/doc-surrealdb/cli/start.mdx
@@ -365,10 +365,10 @@ To use experimental capabilities, set the `SURREAL_CAPS_ALLOW_EXPERIMENTAL` [env
 
 For example, to use record references, set the `SURREAL_CAPS_ALLOW_EXPERIMENTAL` environment variable to `record_references`.
 
-For [graphql](/docs/surrealdb/querying/graphql/surrealist), use `graphql` and for [bearer access](/docs/surrealql/statements/define/access/bearer), use `bearer_access`.
+For [graphql](/docs/surrealdb/querying/graphql/surrealist), use `graphql`, for [bearer access](/docs/surrealql/statements/define/access/bearer), use `bearer_access`, for [DEFINE CONFIG API](/docs/surrealql/statements/define/config) and [DEFINE API](/docs/surrealql/statements/define/api), use `define_api`.
 
 ```bash
-SURREAL_CAPS_ALLOW_EXPERIMENTAL="record_references" surreal start  
+SURREAL_CAPS_ALLOW_EXPERIMENTAL="record_references,graphql" surreal start  
 ```
 
 or, using the `--allow-experimental` flag:
@@ -379,8 +379,8 @@ surreal start --allow-experimental record_references
 Multiple experimental capabilities can be enabled by separating them with a comma.
 
 ```bash
-SURREAL_CAPS_ALLOW_EXPERIMENTAL="record_references, graphql" surreal start
-surreal start --allow-experimental record_references,graphql
+SURREAL_CAPS_ALLOW_EXPERIMENTAL="record_references, graphql, define_api" surreal start
+surreal start --allow-experimental record_references,graphql,define_api
 ```
 
 > [!NOTE]

diff --git a/src/content/doc-surrealdb/integration/http.mdx b/src/content/doc-surrealdb/integration/http.mdx
@@ -128,6 +128,10 @@ You can use the HTTP endpoints to perform the following actions:
             <td scope="row" data-label="Function"><a href="#ml-export"><code>GET /ml/export/:name/:version</code></a></td>
             <td scope="row" data-label="Description">Export a SurrealML model from a specific Namespace and Database</td>
         </tr>
+        <tr>
+            <td scope="row" data-label="Function"><a href="#custom"><code>/api/:namespace/:database/:endpoint</code></a></td>
+            <td scope="row" data-label="Description">Create a custom API endpoint for any number of HTTP methods (GET, POST, etc.)</td>
+        </tr>
     </tbody>
 </table>
 
@@ -2456,3 +2460,60 @@ curl -X GET \
 </TabItem>
 
 </Tabs>
+
+## Custom endpoint at `/api/:ns/:db/:endpoint` {#custom}
+
+<Since v="v2.2.0" />
+> [!CAUTION]
+> Currently, this is an experimental feature as such, it may be subject to breaking changes and may present unidentified security issues. Do not rely on this feature in production applications. To enable this, set the `SURREAL_CAPS_ALLOW_EXPERIMENTAL` [environment variable](/docs/surrealdb/cli/start/#experimental-capabilities) to `define_api`.
+
+
+A custom endpoint can be set using a [`DEFINE API`](/docs/surrealql/statements/define/api) statement. The possible HTTP methods (GET, PUT, etc.) are set using the statement itself. The path begins with `/api`, continues with the namespace and database, and ends with a custom endpoint that can include both static and dynamic path segments.
+
+### Headers
+
+<table>
+    <thead>
+        <tr>
+            <th colspan="2">Header</th>
+            <th colspan="2">Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td colspan="2" scope="row" data-label="Header">
+                <code>Authorization</code>
+                <Label label="optional" >OPTIONAL</Label>
+            </td>
+            <td colspan="2" scope="row" data-label="Description">
+                Sets the root, namespace, or database authentication data
+            </td>
+        </tr>
+        <tr>
+            <td colspan="2" scope="row" data-label="Header">
+                <code>surreal-ns</code>
+                <Label label="required" />
+            </td>
+            <td colspan="2" scope="row" data-label="Description">
+                Sets the selected Namespace for queries.
+            </td>
+        </tr>
+        <tr>
+            <td colspan="2" scope="row" data-label="Header">
+                <code>surreal-db</code>
+                <Label label="required" />
+            </td>
+            <td colspan="2" scope="row" data-label="Description">
+                Sets the selected Database for queries.
+            </td>
+        </tr>
+    </tbody>
+</table>
+
+### Example usage
+
+```bash title="Request"
+curl http://localhost:8000/api/my_namespace/my_database/test_endpoint \
+  -H "surreal-ns: ns" -H "surreal-db: db" \
+  -H "Accept: application/json"
+```
diff --git a/src/content/doc-surrealdb/security/capabilities.mdx b/src/content/doc-surrealdb/security/capabilities.mdx
@@ -5,6 +5,8 @@ title: Capabilities | Security
 description: SurrealDB is secure by default and is suitable for all database use cases. It offers powerful features like scripting, functions or network access from within your SurrealQL queries.
 ---
 
+import Since from "@components/shared/Since.astro";
+
 # Capabilities
 
 SurrealDB is secure by default and is suitable for all database use cases. It offers powerful features like scripting, functions or network access from within your SurrealQL queries. For the strongest security, SurrealDB doesn't allow most of these features by default and instead lets the administrator allow them as needed per use case.
@@ -65,30 +67,41 @@ List of options for allowing capabilities:
             <th colspan="2" scope="col">Description</th>
             <th scope="col">Default</th>
         </tr>
-    </thead>  
+    </thead>
     <tbody>
         <tr>
             <td scope="row" data-label="Option">
-                --allow-scripting
+                -A, --allow-all
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Allow execution of embedded scripting functions
+                Allow all capabilities except for those more specifically denied like experimental features
             </td>
             <td scope="row" data-label="Default">
                 False
             </td>
         </tr>
         <tr>
             <td scope="row" data-label="Option">
-                --allow-guests
+                -A, --allow-arbitrary-query
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Allow non-authenticated users to execute queries when authentication is enabled
+                Denies arbitrary queries to be used by user groups. Possible user groups are: 'guest', 'record', and 'system'.
             </td>
             <td scope="row" data-label="Default">
                 False
             </td>
         </tr>
+        <tr>
+            <td scope="row" data-label="Option">
+                --allow-experimental
+            </td>
+            <td colspan="2" scope="row" data-label="Description">
+                Allow the usage of one or more experimental features (current experimental features are [GraphQL](/docs/surrealdb/querying/graphql) and [Record references](/docs/surrealql/datamodel/references)). Possible values are `graphql`, `record_references`, and `define_api`, separated by a comma.
+            </td>
+            <td scope="row" data-label="Default">
+                None
+            </td>
+        </tr>
         <tr>
             <td scope="row" data-label="Option">
                 --allow-funcs [&lt;target&gt;,...]
@@ -102,32 +115,32 @@ List of options for allowing capabilities:
         </tr>
         <tr>
             <td scope="row" data-label="Option">
-                --allow-net [&lt;target&gt;,...]
+                --allow-guests
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Allow all outbound network access except for network targets that are specifically denied. Alternatively, you can provide a comma-separated list of network targets to allow
+                Allow non-authenticated users to execute queries when authentication is enabled
             </td>
             <td scope="row" data-label="Default">
-                None
+                False
             </td>
         </tr>
         <tr>
             <td scope="row" data-label="Option">
-                --allow-experimental
+                --allow-net [&lt;target&gt;,...]
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Allow the usage of one or more experimental features (current experimental features are [GraphQL](/docs/surrealdb/querying/graphql) and [Record references](/docs/surrealql/datamodel/references)). Possible values are `graphql` and `record_references`, separated by a comma.
+                Allow all outbound network access except for network targets that are specifically denied. Alternatively, you can provide a comma-separated list of network targets to allow
             </td>
             <td scope="row" data-label="Default">
                 None
             </td>
         </tr>
         <tr>
             <td scope="row" data-label="Option">
-                -A, --allow-all
+                --allow-scripting
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Allow all capabilities except for those more specifically denied like experimental features
+                Allow execution of embedded scripting functions
             </td>
             <td scope="row" data-label="Default">
                 False
@@ -145,25 +158,25 @@ List of options for denying capabilities:
             <th colspan="2" scope="col">Description</th>
             <th scope="col">Default</th>
         </tr>
-    </thead>  
+    </thead>
     <tbody>
         <tr>
             <td scope="row" data-label="Option">
-                --deny-scripting
+                -D, --deny-all
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Deny execution of embedded scripting functions
+                Deny all capabilities except for those more specifically allowed
             </td>
             <td scope="row" data-label="Default">
                 False
             </td>
         </tr>
         <tr>
             <td scope="row" data-label="Option">
-                --deny-guests
+                -D, --deny-arbitrary-query
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Deny non-authenticated users to execute queries when authentication is enabled
+                Denies arbitrary queries from being used by user groups. Possible user groups are: 'guest', 'record', and 'system'
             </td>
             <td scope="row" data-label="Default">
                 False
@@ -180,6 +193,17 @@ List of options for denying capabilities:
                 None
             </td>
         </tr>
+        <tr>
+            <td scope="row" data-label="Option">
+                --deny-guests
+            </td>
+            <td colspan="2" scope="row" data-label="Description">
+                Deny non-authenticated users to execute queries when authentication is enabled
+            </td>
+            <td scope="row" data-label="Default">
+                False
+            </td>
+        </tr>
         <tr>
             <td scope="row" data-label="Option">
                 --deny-net [&lt;target&gt;,...]
@@ -193,10 +217,10 @@ List of options for denying capabilities:
         </tr>
         <tr>
             <td scope="row" data-label="Option">
-                -D, --deny-all
+                --deny-scripting
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                Deny all capabilities except for those more specifically allowed
+                Deny execution of embedded scripting functions
             </td>
             <td scope="row" data-label="Default">
                 False
@@ -276,4 +300,12 @@ $ surreal start --allow-net internal.example.com:433
 
 // Allow access to some private networks but not to others
 $ surreal start --allow-net 10.0.0.0/16 --deny-net 10.10.0.0/24
-```
+```
+
+## Arbitrary queries
+
+<Since v="v2.2.0" />
+
+The `--allow-arbitrary-query` and `--deny-arbitrary-query` allows database administrators to allow or deny arbitrary quering by either guest, record or system users, or a combination of those. This capability settings affects the following:  [/sql endpoint](/docs/surrealdb/integration/http#sql), [/key endpoints](/docs/surrealdb/integration/http#get-table), [/graphql endpoint](/docs/surrealdb/integration/http#graphql) and [RPC methods](/docs/surrealdb/integration/rpc) `use`, `select`, `create`, `update`, `merge`, `patch`, `delete`, `relate`, `insert`, `insert_relation`, `query` and `graphql`.
+
+Endpoints that do not accept arbitrary queries such as [`/version`](/docs/surrealdb/integration/http#version) and [authentication endpoints](/docs/surrealdb/integration/http#signin) are not affected.