HTTP & REST
The HTTP endpoints enable simple selection and modifications of all records or a single record in a table, in addition to support for custom SurrealQL queries with multiple statements, using traditional RESTful HTTP url endpoints.
Function | Description |
---|---|
/export GET
|
Exports all data for a specific Namespace and Database |
/health GET
|
Checks the status of the database server and storage engine |
/import POST
|
Imports data into a specific Namespace and Database |
/key/:table GET
|
Selects all records in a table from the database |
/key/:table POST
|
Creates a records in a table in the database |
/key/:table DELETE
|
Deletes all records in a table from the database |
/key/:table/:id GET
|
Selects the specific record from the database |
/key/:table/:id POST
|
Creates the specific record in the database |
/key/:table/:id PUT
|
Updates the specified record in the database |
/key/:table/:id PATCH
|
Modifies the specified record in the database |
/key/:table/:id DELETE
|
Deletes the specified record from the database |
/signup POST
|
Signs-up as a scope user to a specific scope |
/signin POST
|
Signs-in as a root, namespace, database, or scope user |
/sql POST
|
Allows custom SurrealQL queries |
/status GET
|
Checks whether the database web server is running |
/version GET
|
Returns the version of the SurrealDB database server |
GET
/export
endpoint
This HTTP RESTful endpoint exports all data for a specific Namespace and Database.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, or database authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
GET
/health
endpoint
This HTTP RESTful endpoint checks whether the database server and storage engine are running.
The endpoint returns a 200
status code on success and a 500
status code on failure.
POST
/import
endpoint
This HTTP RESTful endpoint imports a set of SurrealQL queries into a specific Namespace and Database.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, or database authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
GET
/key/:table
endpoint
This HTTP RESTful endpoint selects all records in a specific table in the database.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
SELECT * FROM type::table($table);
POST
/key/:table
endpoint
This HTTP RESTful endpoint creates a record in a specific table in the database.
This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object
.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
CREATE type::table($table) CONTENT $body;
DELETE
/key/:table
endpoint
This HTTP RESTful endpoint deletes all records from the specified table in the database.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
DELETE FROM type::table($table);
GET
/key/:table/:id
endpoint
This HTTP RESTful endpoint selects a specific record from the database.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
SELECT * FROM type::thing($table, $id);
POST
/key/:table/:id
endpoint
This HTTP RESTful endpoint creates a single specific record into the database.
This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object
.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
CREATE type::thing($table, $id) CONTENT $body;
PUT
/key/:table/:id
endpoint
This HTTP RESTful endpoint creates or updates a single specific record in the database.
This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object
.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
UPDATE type::thing($table, $id) CONTENT $body;
PATCH
/key/:table/:id
endpoint
This HTTP RESTful endpoint creates or updates a single specific record in the database. If the record already exists, then only the specified fields will be updated.
This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object
.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
UPDATE type::thing($table, $id) MERGE $body;
DELETE
/key/:table/:id
endpoint
This HTTP RESTful endpoint deletes a single specific record from the database.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
Once this endpoint is called the following query will be run on the database:
DELETE FROM type::thing($table, $id);
POST
/signup
endpoint
This HTTP RESTful endpoint is used to create an account inside the SurrealDB database server.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Accept
|
Sets the desired content-type of the response
Can be one of |
The following shows an example request.
curl -X POST \
-H "Accept: application/json" \
-d '{"ns":"test","db":"test","sc":"user_scope","username":"john.doe","password":"123456"}' \
http://localhost:8000/signup
{
"code": 200,
"details": "Authentication succeeded",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
POST
/signin
endpoint
This HTTP RESTful endpoint is used to sign in a user of the SurrealDB database server.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Accept
|
Sets the desired content-type of the response
Can be one of |
The following shows example request on the different permission layers for signin.
Scope:
curl -X POST \
-H "Accept: application/json" \
-d '{"ns":"test","db":"test","sc":"user_scope","username":"john.doe","password":"123456"}' \
http://localhost:8000/signin
{
"code": 200,
"details": "Authentication succeeded",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Namespace:
curl -X POST \
-H "Accept: application/json" \
-d '{"ns":"test","username":"john.doe","password":"123456"}' \
http://localhost:8000/signin
{
"code": 200,
"details": "Authentication succeeded",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Root:
curl -X POST \
-H "Accept: application/json" \
-d '{"username":"john.doe","password":"123456"}' \
http://localhost:8000/signin
{
"code": 200,
"details": "Authentication succeeded",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
POST
/sql
endpoint
The SQL endpoint enables advanced SurrealQL queries.
This HTTP endpoint expects the HTTP body to be a set of SurrealQL statements
.
The following headers can be used to customise the query and the response.
Header | Description |
---|---|
Authorization
|
Sets the root, namespace, database, or scope authentication data |
Accept
|
Sets the desired content-type of the response
Can be one of |
NS
|
Sets the selected Namespace for queries |
DB
|
Sets the selected Database for queries |
The following shows an example request.
curl -X POST \
-u "root:root" \
-H "NS: myapplication" \
-H "DB: myapplication" \
-H "Accept: application/json" \
-d "SELECT * FROM person WHERE age > 18" \
http://localhost:8000/sql
[
{
"time": "14.357166ms",
"status": "OK",
"result": [
{
"age": "23",
"id": "person:6r7wif0uufrp22h0jr0o"
"name": "Simon",
},
{
"age": "28",
"id": "person:6r7wif0uufrp22h0jr0o"
"name": "Marcus",
},
]
}
]
GET
/status
endpoint
This HTTP RESTful endpoint checks whether the database web server is running, returning a 200
status code.
GET
/version
endpoint
This HTTP RESTful endpoint returns the version of the SurrealDB database server.