Working with SurrealDB over HTTP via Postman
SurrealDB provides a RESTful HTTP API for interacting with the database.
In this tutorial, you will learn how to query SurrealDB endpoints via the Postman collection. SurrealDB supports requests via HTTP & Rest with which you can handle different queries from creating simple tables to having Graph relationships between complex tables.
Check out the HTTP & Rest integration documentation for a detailed list of all the endpoints supported.
Prerequisites
This tutorial assumes that you have the following:
- A Postman account to fork the SurrealDB collection
- SurrealDB installed - If you do not, see the installation guide specific to your machine.
Getting Started.
Before forking the Collection from Postman, ensure that you have your SurrealDB instance running locally because by default the collection endpoint is set to localhost:8000 or http://127.0.0.1:8000
To do so run the Start command in your terminal:
surreal start --auth --user root --pass root
The above command enables authentication with --auth and specifies that the user and password are root - Note that this is just for demonstration purposes. You can replace it with any other word.
After running locally, head over to Postman and create a fork for your workspace. You should see all the endpoints listed. You can also check the endpoints in the documentation.
Using INFO Statement
You can get information about your workspace by using the INFO statement. However, you need the right permissions in other to see the output. See the documentation for the INFO statement.
It is also important to note that the namespace and database values for the Postman collection are set to test by default.
You can see the JSON output using the INFO statement in the body of the request
INFO FOR ROOT / DB / NS
Below is the output of querying for the info of the Namespace you can get this output by running
INFO FOR NS
[
{
"result": {
"databases": {
"test": "DEFINE DATABASE test"
},
"tokens": {},
"users": {}
},
"status": "OK",
"time": "190.166µs"
}
]
Defining a Scope User
To define a scope user, first navigate to the POST /sql endpoint and in the header of the request add the following fields:
Accept:application/json
NS:{{namespace}}
DB:{{database}}
You can also define a user with other credentials such as Root or Database user. For this tutorial, we will be using only Scope users.
Note: The Namespace and Database fields are set to the value test by default. You can change this in the collection settings.
In the request body, define the scope human with a session of 24 hours:
DEFINE SCOPE human SESSION 24h
SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
;
The code above allows a user to sign up as a scope user with their email and password. Then hash the password with the crypto::argon2::generate function
The sign in logic gets all the users where the emails match and uses the crypto::argon2::compare function to check the hash value to the unhashed.
Now when you get the info of the Database using INFO for DB you can see the scope human get the following output:
[
{
"result": null,
"status": "OK",
"time": "102.458µs"
},
{
"result": {
"analyzers": {},
"functions": {},
"models": {},
"params": {},
"scopes": {
"human": "DEFINE SCOPE human SESSION 1d SIGNUP (CREATE user SET email = $email, pass = crypto::argon2::generate($pass)) SIGNIN (SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass))"
},
"tables": {},
"tokens": {},
"users": {}
},
"status": "OK",
"time": "78.084µs"
}
]
Signing Up a New Scope user
After defining the signup and signin logic head over to the POST /signup endpoint to signup and in the header of the request add the following fields:
Accept:application/json
namespace:test
database:test
scope:human
In the body of the request add the following information:
{
"ns": "test",
"db": "test",
"sc":"human",
"email": "test@surreal.com",
"pass":"1234567886"
}
The result will be a JSON object:
{
"code": 200,
"details": "Authentication succeeded",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MDcxNDY2NTgsIm5iZiI6MTcwNzE0NjY1OCwiZXhwIjoxNzA3MjMzMDU4LCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOnc2ZzBsNmh5eHpjZzlubTY2dGVjIn0.TZkeHeMS6xrGRXKqFc3-DKY2xADiHU4ydmcUB4ql36VBGow86GrKmjetXSkIcQMl94bHvMui6V3eoTn39TYI3g"
}
Signing in a scope user
Now that we have defined a User we can now log in. To do so, head to the POST /signin and using the same credentials. In the body of the request, add the same information you used to sign up:
{
"ns": "test",
"db": "test",
"sc":"human",
"email": "test3@surreal.com",
"pass":"1234567886"
}
This should return a similar JSON object indicating successful authentication and providing a new token.
{
"code": 200,
"details": "Authentication succeeded",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MDcxNDcxMzcsIm5iZiI6MTcwNzE0NzEzNywiZXhwIjoxNzA3MjMzNTM3LCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOmFtaW1veWU0cHY2djR5MTQ1ajRjIn0.MTJDeaTfMjrpKS8M2A83qo2e5W8_8cnVbOP7r1EL8RCwuHxB-L7miMcE1w8jA00-FBGFQtWpJOH147ap817W6w"
}
Using Table Endpoints
The Postman collection has a couple of endpoints for POST GET PUT PATCH DEL operations. For example, If you want to add a new entry to the table Person (Which is the default table in the collection) go to the POST /key/:table endpoint then in a body of the request and add the table content in the body of the request. E.g:
{
age: 32,
name: 'John'
}
You should get a response as seen below, notice that there is a record ID, with this record ID you can now use any of the /key/:table/:id endpoints for POST GET PUT PATCH DEL operations.
[
{
"result": [
{
"age": 32,
"id": "person:p1cdf6cx89gnfboq5wye",
"name": "John"
}
],
"status": "OK",
"time": "105.667µs"
}
]
Conclusion
In this tutorial, we've walked through how to set up and use SurrealDB over HTTP using Postman. We've covered how to define a new user scope, sign up a new user, and sign in with a user. These steps are crucial for managing user authentication in your applications using SurrealDB.
The Postman collection is still in active development for more information on using surrealDB via the HTTP endpoints. Check out our documentation on HTTP and rest endpoints