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": []
}