REST API 使用说明

REST API 是专为简化与 RESTful API 的交互而设计的软件开发工具包。它封装了 HTTP 请求的细节（如构建和解析），开发者得以专注于实现业务逻辑，从而使用更直观、高效的方式与后端服务进行通信。相比 DolphinDB Json API，DolphinDB REST API 的请求格式更加简易、更便于使用。

目前 DolphinDB REST API 已支持 login 和 execute 功能，分别用于登录账户和执行脚本。目前仅支持处理标量、向量、表、字典、集合形式的数据。

与 Json API 的请求格式对比

  • Json API

Json API 传参需要给出要执行的函数名字 functionName，以及每个参数的 name, form, type 和 value。

请求 URL：serverip:port/sessionID

请求体：

paramJson = {
	"functionName": "executeCode",
	"params": [{
		"name": "script",
		"form": "scalar",
		"type": "string",
		"value": "select * from table(1..3 as id,'tom' 'bob' 'tony' as name)"
	}]
}

  • REST API

REST API 按照 RESTful 风格规定好了每个接口传入参数的格式，可以简化需要用户手动输入的信息。

请求 URL：serverip:port/api/execute

请求体：

{
  "script" : "select * from table(1..3 as id,'tom' 'bob' 'tony' as name)"
}

系统要求

DolphinDB server：请使用 3.00.2，2.00.14 及以上版本。

接口介绍

目前仅支持两个接口：login 和 execute 。用户通过 login 接口获取 userToken，在后续请求中带着该 token 来执行需要权限的操作。

login

功能描述：向 serverip:port/api/login 发送带有 username 和 password 的请求，并得到返回的 userToken。

请求 URL：serverip:port/api/login

请求体：

{ 
    "username": "parameter1", //用户名
    "password": "parameter2" //密码
}

返回值：一个 Json，格式如下

示例：

{
    "session": sessionID,
    "user": 用户名,
    "code": 成功时为0，失败时为1,
    "message": 错误信息,
    "result": [userToken]
}

请求 URL：127.0.0.1:8848/api/login

请求体：

curl --location --request POST '192.168.0.101:8300/api/login' \
--data '{
    "username": "admin",
    "password": "123456"
}'

成功时返回：

{
    "session": "2333906441",
    "user": "admin",
    "code": "0",
    "message": "",
    "result": ["FxKFp5KlRUwUz173s11/ao8aSkruVRUplA9Aa1oIdnb709wz4pb96/e7hoU2oiHY\nst9iClYjZtwuBbmLsr0qNXJDlcaSdBO4ltojGROOpItVE45zWqnlPfEKKgMsh5Lp\nbiT78vnHRprfX/skAInekI6pxpRztff9TYKV98kq0l0=\n"]
}
失败时返回：
{
    "session": "2333906441",
    "user": "admin",
    "code": "1",
    "message": "login("admin1", "123213") => The user name or password is incorrect.",
    "result": []
}

execute

功能描述：向 serverip:port/api/execute 发送一段脚本并执行。注意：

  • 如果脚本中若带有需要特定权限的操作，需要先通过 login 接口得到 userToken，并在请求 header 中带上 userToken 才能成功执行。

  • 如果需要与之前的操作共用一个 session，则需要在请求 header 中传入 sessionId。

请求 URL：serverip:port/api/login

请求 header：
curl --location '192.168.0.101:8300/api/execute' \
--header 'Authorization: Bearer KCRfCqOaWkwv3QCQaCv5K314Ecy9d36uKZW9J6CHx+dcqME2Vp0oXCJEy0/B5y7Z\nWRz9NgrMWXrgsowTVhlm0Cdvu5uR95u+7c08AOQptcxMXxSEjFBtOl8YGl2fQJsK\nkhDu9/V0nyFXZBvnJNSItx7soueAEDc/rk92RYlpyAA=\n' \
--data '{
    "script": "createUser(\"user1\", \"123456\");createUser(\"user2\", \"123456\");"
}'
请求体：
{
	"script": "example1",//执行脚本
	"offset": "example2",// 返回结果的分页偏移量，默认0，可省略
	"length": "example3"// 返回结果的分页页面大小，默认1024，可省略
}

返回值：一个 Json，格式为：

{
    "session": sessionID,
    "user": 用户名,
    "code": 成功时为0，失败时为1,
    "message": 错误信息,
    "result": [toStdJson(执行结果)]
}

示例：

请求 URL：127.0.0.1:8848/api/execute

请求 header：

Authorization: Bearer FxKFp5KlRUwUz173s11/ao8aSkruVRUplA9Aa1oIdnb709wz4pb96/e7hoU2oiHY\nst9iClYjZtwuBbmLsr0qNXJDlcaSdBO4ltojGROOpItVE45zWqnlPfEKKgMsh5Lp\nbiT78vnHRprfX/skAInekI6pxpRztff9TYKV98kq0l0=\n
sessionID: 2333906441 //可选

请求体成功时的返回：

请求
curl --location '192.168.0.101:8300/api/execute' \
--data '{
    "script": "select * from table(1..3 as id,'\''tom'\'' '\''bob'\'' '\''tony'\'' as name)",
    "offset": 0,
    "length": 1
}'

成功时返回：
{
    "session": "20267359",
    "user": "",
    "code": 0,
    "message": "",
    "result": [
        [
            {
                "id": 1,
                "name": "tom"
            }
        ]
    ]
}

请求体及失败时的返回结果：

请求：
{
    "script": "select * from table(1..2 as id,'tom' 'bob' 'tony' as name)"
}

返回报错：
{
    "session": "2333906441",
    "user": "",
    "code": 1,
    "message": "select * from table(1 .. 2 as id, ["tom","bob","tony"] as name) => All columns must be of the same length. RefId:S02010",
    "result": []
}