From 408436c1fa3c2906b822066519f5c945ff7d4acf Mon Sep 17 00:00:00 2001 From: Dave MacLeod <56599343+Dhghomon@users.noreply.github.com> Date: Sat, 14 Sep 2024 23:03:10 +0900 Subject: [PATCH] Http protocol page improvements (#839) Co-authored-by: ekwuno --- .../version-latest/integration/http.mdx | 1362 ++++++++++++++--- .../querying/surrealql/http.mdx | 62 +- 2 files changed, 1232 insertions(+), 192 deletions(-) diff --git a/doc-surrealdb_versioned_docs/version-latest/integration/http.mdx b/doc-surrealdb_versioned_docs/version-latest/integration/http.mdx index 5d7b2f64e..3d29bb625 100644 --- a/doc-surrealdb_versioned_docs/version-latest/integration/http.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/integration/http.mdx @@ -4,7 +4,10 @@ sidebar_label: HTTP & Rest title: HTTP Protocol | Integration description: The HTTP endpoints enable selection and modification of data, along with custom SurrealQL queries, using traditional RESTful HTTP endpoints. --- + import Since from '@site/src/components/Since'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; # HTTP & Rest @@ -12,16 +15,16 @@ The HTTP endpoints enable simple selection and modifications of all records or a ## Accessing Endpoints via Postman -You can access these endpoints via Postman. To do so, follow these steps: +The most convenient way to access these endpoints is via SurrealDB's Postman Collection. To do so, follow these steps: 1. Open Postman 2. Clone the [SurrealDB Postman Collection](https://postman.com/surrealdb/workspace/surrealdb/collection/19100500-3da237f3-588b-4252-8882-6d487c11116a) -2. Select the appropriate HTTP method (GET, POST, etc.). +2. Select the appropriate HTTP method (`GET /health`, `DEL /key/:table`, etc.). 3. Enter the endpoint URL. 4. If the endpoint requires any parameters or a body, make sure to include those in your request. :::note -__Note:__ 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 Start command in the [CLI](/docs/surrealdb/cli/start), before querying the endpoints. +__Note:__ 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. ::: You can use the HTTP endpoints to perform the following actions: @@ -129,6 +132,23 @@ You can use the HTTP endpoints to perform the following actions: This HTTP RESTful endpoint checks whether the database web server is running, returning a 200 status code. +### Example usage + +```bash title="Request" +curl -I http://localhost:8000/status +``` + +```bash title="Sample output" +HTTP/1.1 200 OK +content-length: 0 +vary: origin, access-control-request-method, access-control-request-headers +access-control-allow-origin: * +surreal-version: surrealdb-2.0.0+20240910.8f30ee08 +server: SurrealDB +x-request-id: 3dedcc96-4d8a-451e-b60d-4eaac14fa3f8 +date: Wed, 11 Sep 2024 00:52:49 GMT +``` +
## `GET /health` {#health} @@ -137,12 +157,38 @@ This HTTP RESTful endpoint checks whether the database server and storage engine The endpoint returns a `200` status code on success and a `500` status code on failure. +```bash title="Request" +curl -I http://localhost:8000/health +``` + +```bash title="Sample output" +HTTP/1.1 200 OK +content-length: 0 +vary: origin, access-control-request-method, access-control-request-headers +access-control-allow-origin: * +surreal-version: surrealdb-2.0.0+20240910.8f30ee08 +server: SurrealDB +x-request-id: 24a1e675-af50-4676-b8ff-6eee18e9a077 +date: Wed, 11 Sep 2024 00:53:22 GMT +``` +
## `GET /version` {#version} This HTTP RESTful endpoint returns the version of the SurrealDB database server. +### Example usage + +```bash title="Request" +curl http://localhost:8000/version +``` + +```bash title="Sample output" +surrealdb-2.0.0+20240910.8f30ee08 +``` + +
## `POST /import` {#import} @@ -150,6 +196,10 @@ This HTTP RESTful endpoint returns the version of the SurrealDB database server. This HTTP RESTful endpoint imports a set of SurrealQL queries into a specific Namespace and Database. ### Headers + + + + @@ -178,29 +228,99 @@ This HTTP RESTful endpoint imports a set of SurrealQL queries into a specific Na + + +
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, or database authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries.
+ + + ### Example usage + +:::note + Note: The `-u` in the example below is a shorthand used by curl to send an Authorization header. +::: + + + + ```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 ``` + + + +```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 +``` + + + +
@@ -209,6 +329,10 @@ curl -X POST -u "root:root" -H "NS: mynamespace" -H "DB: mydatabase" -H "Accept: This HTTP RESTful endpoint exports all data for a specific Namespace and Database. ### Headers + + + + @@ -228,29 +352,89 @@ This HTTP RESTful endpoint exports all data for a specific Namespace and Databas + + +
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, or database authentication data +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries.
+ + + ### Example usage + +:::note + Note: The `-u` in the example below is a shorthand used by curl to send an Authorization header, while `-o` allows the output to be written to a file. +::: + + + + +```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 +``` + + + ```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 "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -o path/to/file.surql http://localhost:8000/export ``` + + +
@@ -259,10 +443,10 @@ curl -X GET -u "root:root" -H "NS: mynamespace" -H "DB: mydatabase" -H "Accept: ```json title="Method and URL" POST /signin ``` -This HTTP RESTful endpoint is used to access an existing account inside the SurrealDB database server. -The following headers can be used to customise the query and the response. +This HTTP RESTful endpoint is used to access an existing account inside the SurrealDB database server. +### Headers @@ -281,9 +465,22 @@ The following headers can be used to customise the query and the response. Sets the desired content-type of the response + +
+ +### Data + + + + + + + + + @@ -328,7 +526,12 @@ The following headers can be used to customise the query and the response.
DataDescription
- NS + ns REQUIRED FOR DB & RECORD @@ -292,7 +489,7 @@ The following headers can be used to customise the query and the response.
- DB + db REQUIRED FOR RECORD @@ -301,10 +498,11 @@ The following headers can be used to customise the query and the response.
- AC + ac + REQUIRED FOR RECORD USER - Specifies the access method + The record access method to use for signing in.
+:::note + Note: The `ac` parameter is only required if you are signing in using an [access method](/docs/surrealql/statements/define/access) as a record user. For system users on the database, namespace, and root level, this parameter can be omitted. +::: + ### Example with a Record user + ```bash title="Request" curl -X POST -H "Accept: application/json" -d '{"ns":"test","db":"test","ac":"users","user":"john.doe","pass":"123456"}' http://localhost:8000/signin ``` @@ -342,6 +545,7 @@ curl -X POST -H "Accept: application/json" -d '{"ns":"test","db":"test","ac":"us ``` ### Example with Namespace user + ```bash title="Request" curl -X POST -H "Accept: application/json" -d '{"ns":"test","user":"john.doe","pass":"123456"}' http://localhost:8000/signin ``` @@ -355,6 +559,7 @@ curl -X POST -H "Accept: application/json" -d '{"ns":"test","user":"john.doe","p ``` ### Example with Root user + ```bash title="Request" curl -X POST -H "Accept: application/json" -d '{"user":"john.doe","pass":"123456"}' http://localhost:8000/signin ``` @@ -369,7 +574,7 @@ curl -X POST -H "Accept: application/json" -d '{"user":"john.doe","pass":"123456 ### Example usage via Postman -After you have defined the users permissions, you can use the `POST /signin` endpoint to sign in as a user. +After you have defined the users permissions for the record user, you can use the `POST /signin` endpoint to sign in as a user. Using the [user credentials](/docs/surrealdb/security/authentication#record-users) created add the following to the request body: ```json @@ -382,10 +587,6 @@ Using the [user credentials](/docs/surrealdb/security/authentication#record-user } ``` -:::note - Note: The `ac` parameter is only required if you are signing in using an [access method](/docs/surrealql/statements/define/access), otherwise you can omit it for database, namespace and root users. -::: -
@@ -394,7 +595,8 @@ Using the [user credentials](/docs/surrealdb/security/authentication#record-user This HTTP RESTful endpoint is used to create an account inside the SurrealDB database server. -### Headers +### Header + @@ -412,9 +614,22 @@ This HTTP RESTful endpoint is used to create an account inside the SurrealDB dat Sets the desired content-type of the response + +
+ +### Data + + + + + + + + + + + + + + + + +
DataDescription
- namespace + ns REQUIRED FOR DB & RECORD @@ -423,7 +638,7 @@ This HTTP RESTful endpoint is used to create an account inside the SurrealDB dat
- database + db REQUIRED FOR RECORD @@ -436,13 +651,32 @@ This HTTP RESTful endpoint is used to create an account inside the SurrealDB dat REQUIRED FOR RECORD - The record access method to use for signing up. Also pass any variables used in the signup query + The record access method to use for signing up. +
+ user + REQUIRED FOR ROOT, NS & DB + + The username of the database user +
+ pass + REQUIRED FOR ROOT, NS & DB + + The password of the database user
### Example usage + ```bash title="Request" curl -X POST -H "Accept: application/json" -d '{"ns":"test","db":"test","ac":"users","user":"john.doe","pass":"123456"}' http://localhost:8000/signup ``` @@ -509,6 +743,10 @@ The above query defines a record access method called `account` that allows user This HTTP RESTful endpoint selects all records in a specific table in the database. ### Headers + + + + @@ -537,41 +775,27 @@ This HTTP RESTful endpoint selects all records in a specific table in the databa
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ -### Translated query -```surql -SELECT * FROM type::table($table); -``` - -
- -## `POST /key/:table` {#post-table} - -This HTTP RESTful endpoint creates a record in a specific table in the database. - -:::note -This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL `object`. -::: - -### Headers + @@ -600,41 +824,48 @@ This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL `object`.
- NS + surreal-ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + surreal-db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ + + + -### translated query +### Translated query ```surql -CREATE type::table($table) CONTENT $body; +SELECT * FROM type::table($table); ``` -
-## `PUT /key/:table` {#put-table} +## `POST /key/:table` {#post-table} -This HTTP RESTful endpoint updates all records in a specific table in the database. +This HTTP RESTful endpoint creates a record in a specific table in the database. :::note -This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. +This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL `object`. ::: ### Headers + + + + @@ -663,41 +894,27 @@ This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ -### Translated query -```surql -UPDATE type::table($table) CONTENT $body; -``` - -
- -## `PATCH /key/:table` {#patch-table} - -This HTTP RESTful endpoint modifies all records in a specific table in the database. - -:::note -This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. -::: - -### Headers + @@ -726,39 +943,632 @@ This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.
- NS + surreal-ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + surreal-db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ + + ### Translated query ```surql -UPDATE type::table($table) MERGE $body; +CREATE type::table($table) CONTENT $body; ```
-## `DELETE /key/:table` {#delete-table} +## `PUT /key/:table` {#put-table} -This HTTP RESTful endpoint deletes all records from the specified table in the database. +This HTTP RESTful endpoint updates all records in a specific table in the database. -### Headers - - +:::note +This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. +::: + +### Headers + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ ns + REQUIRED + + Sets the selected Namespace for queries. +
+ db + REQUIRED + + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries. +
+ + + + +### Translated query +```surql +UPDATE type::table($table) CONTENT $body; +``` + +
+ +## `PATCH /key/:table` {#patch-table} + +This HTTP RESTful endpoint modifies all records in a specific table in the database. + +:::note +This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. +::: + +### Headers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ ns + REQUIRED + + Sets the selected Namespace for queries. +
+ db + REQUIRED + + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries. +
+ + + + +### Translated query +```surql +UPDATE type::table($table) MERGE $body; +``` + +
+ +## `DELETE /key/:table` {#delete-table} + +This HTTP RESTful endpoint deletes all records from the specified table in the database. + +### Headers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ ns + REQUIRED + + Sets the selected Namespace for queries. +
+ db + REQUIRED + + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries. +
+ + + + +### Translated query +```surql +DELETE FROM type::table($table); +``` + +
+ +## `GET /key/:table/:id` {#get-record} + +This HTTP RESTful endpoint selects a specific record from the database. + +### Headers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ ns + REQUIRED + + Sets the selected Namespace for queries. +
+ db + REQUIRED + + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries. +
+ + + +### Translated query +```surql +SELECT * FROM type::thing($table, $id); +``` + +
+ +## `POST /key/:table/:id` {#post-record} + +This HTTP RESTful endpoint creates a specific record in a table in the database. + +### Headers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ ns + REQUIRED + + Sets the selected Namespace for queries. +
+ db + REQUIRED + + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries. +
+ + + + +### Translated query +```surql +CREATE type::thing($table, $id) CONTENT $body; +``` + +
+ +## `PUT /key/:table/:id` {#put-record} + +This HTTP RESTful endpoint updates a specific record in a table in the database. + +:::note +This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. +::: + +### Headers + + + + + + @@ -785,37 +1595,27 @@ This HTTP RESTful endpoint deletes all records from the specified table in the d
Header Description
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ -### Translated query -```surql -DELETE FROM type::table($table); -``` - -
- -## `GET /key/:table/:id` {#get-record} - -This HTTP RESTful endpoint selects a specific record from the database. - -### Headers + @@ -844,37 +1644,48 @@ This HTTP RESTful endpoint selects a specific record from the database.
- NS + surreal-ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + surreal-db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ + + ### Translated query ```surql -SELECT * FROM type::thing($table, $id); +UPDATE type::thing($table, $id) CONTENT $body; ```
-## `POST /key/:table/:id` {#post-record} +## `PATCH /key/:table/:id` {#patch-record} -This HTTP RESTful endpoint creates a specific record in a table in the database. +This HTTP RESTful endpoint modifies a specific record in a table in the database. + +:::note +This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. +::: ### Headers + + + + @@ -903,41 +1714,27 @@ This HTTP RESTful endpoint creates a specific record in a table in the database.
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ -### Translated query -```surql -CREATE type::thing($table, $id) CONTENT $body; -``` - -
- -## `PUT /key/:table/:id` {#put-record} - -This HTTP RESTful endpoint updates a specific record in a table in the database. - -:::note -This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. -::: - -### Headers + @@ -966,41 +1763,44 @@ This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.
- NS + surreal-ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + surreal-db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ + + ### Translated query ```surql -UPDATE type::thing($table, $id) CONTENT $body; +UPDATE type::thing($table, $id) MERGE $body; ```
-## `PATCH /key/:table/:id` {#patch-record} - -This HTTP RESTful endpoint modifies a specific record in a table in the database. +## `DELETE /key/:table/:id` {#delete-record} -:::note -This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object. -::: +This HTTP RESTful endpoint deletes a single specific record from the database. ### Headers + + + + @@ -1029,37 +1829,27 @@ This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ -### Translated query -```surql -UPDATE type::thing($table, $id) MERGE $body; -``` - -
- -## `DELETE /key/:table/:id` {#delete-record} - -This HTTP RESTful endpoint deletes a single specific record from the database. - -### Headers + @@ -1088,24 +1878,27 @@ This HTTP RESTful endpoint deletes a single specific record from the database.
- NS + surreal-ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + surreal-db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries.
+ + + ### Translated query ```surql @@ -1123,6 +1916,10 @@ The SQL endpoint enables use of SurrealQL queries. ::: ### Headers + + + + @@ -1151,29 +1948,98 @@ The SQL endpoint enables use of SurrealQL queries. + + +
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries.
+ + + ### Example usage + +:::note + Note: The `-u` in the example below is a shorthand used by curl to send an Authorization header. +::: + + + + +```bash title="Request" +curl -X POST -u "root:root" -H "ns: mynamespace" -H "db: mydatabase" -H "Accept: application/json" -d "SELECT * FROM person WHERE age > 18" http://localhost:8000/sql +``` + + + ```bash title="Request" -curl -X POST -u "root:root" -H "NS: mynamespace" -H "DB: mydatabase" -H "Accept: application/json" -d "SELECT * FROM person WHERE age > 18" http://localhost:8000/sql +curl -X POST -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -d "SELECT * FROM person WHERE age > 18" http://localhost:8000/sql ``` + + + ```json title="Response" [ @@ -1209,6 +2075,7 @@ The GraphQL endpoint enables use of GraphQL queries to interact with your data. ::: ### Headers + @@ -1257,9 +2124,20 @@ The GraphQL endpoint enables use of GraphQL queries to interact with your data.
### Example usage + +:::note + Note: The `-u` in the example below is a shorthand used by curl to send an Authorization header. +::: + + + + ```bash title="Request" -curl -X POST -u "root:root" -H "NS: mynamespace" -H "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 ``` + + + ```json title="Response" [ @@ -1289,6 +2167,10 @@ curl -X POST -u "root:root" -H "NS: mynamespace" -H "DB: mydatabase" -H "Accept: This HTTP RESTful endpoint imports a SurrealML machine learning model into a specific Namespace and Database. It expects the file to be a SurrealML file packaged in the `.surml` file format. As machine learning files can be large, the endpoint expects a chunked HTTP request. ### Headers + + + + @@ -1308,29 +2190,89 @@ This HTTP RESTful endpoint imports a SurrealML machine learning model into a spe + + +
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries.
+ + + ### Example usage + +:::note + Note: The `-u` in the example below is a shorthand used by curl to send an Authorization header. +::: + + + + +```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 +``` + + + ```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 "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -d path/to/file.surml http://localhost:8000/ml/import ``` + + + ### Usage in Python @@ -1350,6 +2292,10 @@ SurMlFile.upload("./linear_test.surml", url, 5) This HTTP RESTful endpoint exports a SurrealML machine learning model from a specific Namespace and Database. The output file with be a SurrealML file packaged in the `.surml` file format. As machine learning files can be large, the endpoint outputs a chunked HTTP response. ### Headers + + + + @@ -1369,26 +2315,86 @@ This HTTP RESTful endpoint exports a SurrealML machine learning model from a spe + + +
- NS + ns REQUIRED - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
- DB + db REQUIRED - Sets the selected Database for queries + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, or database authentication data +
+ surreal-ns + REQUIRED + + Sets the selected Namespace for queries. +
+ surreal-db + REQUIRED + + Sets the selected Database for queries.
+ + + ### Example usage + +:::note + Note: The `-u` in the example below is a shorthand used by curl to send an Authorization header, while `-o` allows the output to be written to a file. +::: + + + + ```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 ``` + + + +```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 +``` + + + \ No newline at end of file diff --git a/doc-surrealdb_versioned_docs/version-latest/querying/surrealql/http.mdx b/doc-surrealdb_versioned_docs/version-latest/querying/surrealql/http.mdx index c27c8f522..522652835 100644 --- a/doc-surrealdb_versioned_docs/version-latest/querying/surrealql/http.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/querying/surrealql/http.mdx @@ -26,6 +26,10 @@ The `/sql` endpoint enables use of SurrealQL queries. ::: ### Headers + + + + @@ -56,59 +60,90 @@ The `/sql` endpoint enables use of SurrealQL queries. + + +
NS REQUIRED - V1.x - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
DB REQUIRED - V1.x - Sets the selected Database for queries + Sets the selected Database for queries. +
+ + + + + + + + + + + + + + + + + +
HeaderDescription
+ Authorization + OPTIONAL + + Sets the root, namespace, database, or record authentication data +
+ Accept + REQUIRED + + Sets the desired content-type of the response
surreal-ns REQUIRED - V2.x - Sets the selected Namespace for queries + Sets the selected Namespace for queries.
surreal-db REQUIRED - V2.x - Sets the selected Database for queries + Sets the selected Database for queries.
+ + + ### Example usage -```bash title="Request" -curl -X POST -u "root:root" -H "NS: mynamespace" -H "DB: mydatabase" -H "Accept: application/json" -d "SELECT * FROM person WHERE age > 18" http://localhost:8000/sql -``` + +:::note + Note: The `-u` in the example below is a shorthand used by curl to send an Authorization header. +::: - + ```bash title="Request" curl -X POST -u "root:root" -H "NS: mynamespace" -H "DB: mydatabase" -H "Accept: application/json" -d "SELECT * FROM person WHERE age > 18" http://localhost:8000/sql ``` - + ```bash title="Request" curl -X POST -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -d "SELECT * FROM person WHERE age > 18" http://localhost:8000/sql ``` @@ -116,7 +151,6 @@ curl -X POST -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatab - ```json title="Response" [ {