Back to top
  Back

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
/sql POST Allows custom SurrealQL queries
/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

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
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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 "Content-Type: 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 /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
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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 SurrealQL object.

The following headers can be used to customise the query and the response.

Header Description
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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 SurrealQL object.

The following headers can be used to customise the query and the response.

Header Description
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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 SurrealQL object.

The following headers can be used to customise the query and the response.

Header Description
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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 SurrealQL object.

The following headers can be used to customise the query and the response.

Header Description
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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
Authorisation Sets the root, namespace, database, or scope authentication data
Content-Type Sets the desired content-type of the response
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);