REST API
DolphinDB REST API enables interaction with the DolphinDB server through HTTP requests. Compared to the DolphinDB JSON API, the REST API offers simpler, RESTful request formats that align better with common user practices.
Currently, the DolphinDB REST API provides two methods: login
for user
authentication and execute
for script execution. Supported data forms
include scalars, vectors, tables, dictionaries, and sets.
System Requirements
DolphinDB server version 2.00.14/3.00.2 or higher.
API Reference
Login (api/login
)
Login via user name and password. Get a user token upon authentication, which can be used in later operations requiring specific user privileges.
Request
- URL:
<serverip>:<port>/api/login
- Method: POST
- Body:
- username: User's username
- password: User's password
Response
JSON object containing:
- session: Session ID
- user: Username
- code: "0" (login success) or "1" (login failure)
- message: Error message (empty on success)
- result: Array containing user token (empty on failure)
Example
Request:
curl --location --request POST '127.0.0.1:8848/api/login' \
--data '{"username": "admin", "password": "123456"}'
Success response:
{
"session": "2333906441",
"user": "admin",
"code": "0",
"message": "",
"result": ["kRYEw4RK2m/x1G4Qdl7hpqf+wscfxTFkI1rTI7z0Cdea7eiZ5LkKwZEf/fAC46EX\nPIgIfppIWo1uhExIn9QDyOJNa7Hyr1B85GF+CWgsE8BGeOJROcdYQypVLUzDva89\nk/BC2hCS99OcCNk3zwu/cJh5133+dHnWGX8oluqj1NI=\n"]
}
Failure response:
{
"session": "2333906441",
"user": "admin",
"code": "1",
"message": "login("admin1", "123213") => The user name or password is incorrect.",
"result": []
}
Execute Script (api/execute
)
Execute DolphinDB scripts.
Request
- URL:<serverip>:<port>/api/execute
- Method: POST
- Headers:
- Authorization: optional, user token required for privileged operations. Use the pattern Bearer <userToken> where <userToken> can be obtained from api/login.
- sessionID: Session ID (optional, for using the same session as a previous request)
- Body:
- script: DolphinDB script to execute
- offset: optional, default 0. Pagination offset for the returned results.
- length: optional, default 1024. Page size for the returned results.
Response
JSON object containing:
- session: Session ID
- user: Username
- code: 0 (execution success) or 1 (execution failure)
- message: Error message (empty on success)
- result: Script execution result in JSON format
Example
Request:
curl --location 'http://127.0.0.1:8848/api/execute' \
--header 'Authorization: Bearer kRYEw4RK2m/x1G4Qdl7hpqf+wscfxTFkI1rTI7z0Cdea7eiZ5LkKwZEf/fAC46EX\nPIgIfppIWo1uhExIn9QDyOJNa7Hyr1B85GF+CWgsE8BGeOJROcdYQypVLUzDva89\nk/BC2hCS99OcCNk3zwu/cJh5133+dHnWGX8oluqj1NI=\n' \
--data '{
"script": "createUser(`JohnSmith, '\''123456'\'');createUser(`LeeJones, '\''123456'\'');table(1 2 as ID, '\''John'\'''\''Lee'\'' as Name)",
"offset": 0,
"length": 1
}'
Success Response:
{
"session": "638252939",
"user": "admin",
"code": 0,
"message": "",
"result": [
[
{
"ID": 1,
"Name": "John"
}
]
]
}
Failure Response:
{
"session": "638252939",
"user": "admin",
"code": 1,
"message": "createUser("JohnSmith", "123456") => The user [JohnSmith] is already there.",
"result": []
}