RESTPP请求

用户提交请求的过程从本质上说，是将一个HTTP请求发送给对应的REST++服务器的过程。默认情况下，REST++服务器的监听端口为9000。每一个请求命令都必须包含下面的三个要素：

1. 请求方法（包括GET、POST或DELETE）

2. 端点地址

3. 必须的参数和可选的参数

端点地址以HTTP URL的形式表示。

参数附加在末尾，并使用标准的HTTP请求字符串格式：

在测试环境或开发环境中，提交请求的一方和收到请求的REST++服务器可能位于同一台计算机上。在这种情况下，服务器的IP地址server_ip可以写成localhost。

通常情况下，向REST++服务器提交HTTP请求的最方便方式是使用Linux的curl命令。

REST请求格式

curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters"

例:

假定REST++服务器位于本地计算机上（典型配置），且同时TigerGraph数据库中有一个叫做socialNEet的图。则如果用户试图获得socialNet图上的所有 User 点，则命令将写为：

例: 获得所有用户点

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User"

如果只想获得前三个点，则可以将limit参数设定为3：

例: 获得三个用户点

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

HTTP请求中的三个方法关键字————即GET、POST和DELETE三个字段是大小写敏感的。同时，curl命令的选项标记（option flag）也是大小写敏感的。

POST方法的数据输入

在POST请求中，输入的数据必须为JSON格式。输入数据的方法有两种，即命令行嵌入式或文件导入式。

命令行嵌入式

数据必须处理为一条单行字符串，不能有分行符。在curl命令中添加- d参数，然后加上对应的JSON字符串。

POST请求中嵌入源数据的语法格式

curl -X POST -d 'json_string' "http://server_ip:9000/path_to_endpoint?request_parameters"

下面的例子中，我们使用POST /graph端点，向socialNet图中插入一个id为 “id6” 的点类为User的点。

例：使用嵌入式方法输入数据

curl -X POST -d '{"vertices":{"User":{"id6":{"id":{"value":"id6"}}}}}' "http://localhost:9000/graph/socialNet"

文件导入式

通常，使用单独的文件导入数据会更加方便，特别是当数据量比较大的时候。

可以在curl命令中添加 --data-binary @path_to_file 参数来引用数据文件，

例：POST请求中通过文件导入数据的语法

curl -X POST --data-binary @json_file "http://server_ip:9000/path_to_endpoint?request_parameters"

如果把前面的例子中的源数据改为由文件导入（假设文件名为：my_input.json），则对应的命令行变为：

例：使用文件导入数据

curl -X POST --data-binary @my_input.json "http://localhost:9000/graph/socialNet"

REST++的输出

在TigerGraph中，所有的REST输出都是JSON格式的。在本指导的“内建端点”部分可以找到所有内建端点的格式详述。默认情况下，输出的结果是机器阅读格式，即不会有多余的空格和回车。输出的JSON对象有三个字段：错误（error）、消息（message）和结果（result）。

本文档中所有的JSON格式均以v2版本的API为基础。对于早期使用v1版本API的TigerGraph来说，其输出的结果可能和v2版本的输出略有差异。在新版的TigerGraph系统中，用户可自行选择v1或v2版本的格式输出。

为了使得输出的结果更加便于阅读，用户可以使用jq command或Python的内建json库来对输出结果调整格式。绝大多数的Linux安装包中都默认安装了这些组件。

curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | jq .
curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | python -m json.tool

例:

在文档GSQL Demo Examples 文档中的Collaborative Filter案例中，包含了如下请求：

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

如果输出结果没有被处理过，它是这样的：

{"version":{"api":"v2","schema":0},"error":false,"message":"","results":[{"v_id":"id2","v_type":"User","attributes":{}},{"v_id":"id5","v_type":"User","attributes":{}},{"v_id":"id3","v_type":"User","attributes":{}}]}

如果我们对结果进行格式修改：

curl -X GET http://localhost:9000/graph/socialNet/vertices/User?limit=3 | jq .

则输出的内容便更易于阅读了：

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "v_id": "id2",
      "v_type": "User",
      "attributes": {}
    },
    {
      "v_id": "id5",
      "v_type": "User",
      "attributes": {}
    },
    {
      "v_id": "id3",
      "v_type": "User",
      "attributes": {}
    }
  ]
}

REST++的安全验证

TigerGraph管理员可以选择是否在REST++端点上开启用户验证。如果用户验证处于关闭状态，则TigerGraph的REST++端点是公开的，任何可以访问该服务器HTTP端口的用户都能够调用该REST++端点。然而，当用户验证开启后，要调用REST++端点则必须在HTTP头中添加有效的用户身份令牌。请参阅文档用户权限及验证查看开启/关闭用户验证的具体步骤。

TigerGraph的REST++服务使用OAuth 2.0验证规范：每个用户需要创建一条或多条密文（即secret，格式为一个伪随机字符串）。每条密文对应某个特定用户在特定图上的特定权限。任何人只要拥有该密文，即可以在特定的REST端点上生成一个用于验证身份的令牌（即token，同样也是一个伪随机字符串）。令牌用于通过REST端点执行TigerGraph数据库操作。每个令牌都会在一定时间后失效。默认情况下，令牌的有效期为一个月。

通过GET /requesttoken获得一个令牌

用户在获取令牌前必须首先拥有密文。可以在文档用户权限及验证中找到从GSQL中获取密文的方法。端点GET /requesttoken专门用于生成令牌。该端点需要两个输入参数：

• secret (必须): 即用户的密文

• lifetime (可选): 令牌的有效时间（单位为秒）。默认有效期为一个月，约合2600万秒。

例：通过REST++请求获得令牌"

curl -X GET 'localhost:9000/requesttoken?secret=jiokmfqqfu2f95qs6ug85o89rpkneib3&lifetime=1000000'

使用令牌

当REST++端点上的用户验证功能打开时，我们必须在每一个HTTP请求的头部都包含有效的令牌。如果我们使用的是curl命令提交REST++请求，则语法格式如下：

通过curl提交包含用户验证信息的请求

curl -X GET -H "Authorization: Bearer <token>" '<request_URL>'

例：假设令牌为 “01234567abcdefgh01234567abcdefgh”，则Collaborative Filtering案例中的请求应写成如下样式：

curl -X GET -H "Authorization: Bearer 01234567abcdefgh01234567abcdefgh" "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

大小限制

一条URL请求的最长长度限制为8K字节（包含查询字符串）。如果字符串中内嵌的数据过长，建议使用文件导入法输入数据。

请求主体（包括内嵌的数据）的最大长度取决于系统参数nginx.client_max_body_size的值。该值默认值为128（单位MB）。下面的命令可以提高该限制值：

gadmin --set nginx.client_max_body_size xxx -f

该参数的上限为1024MB。提高该参数的值会降低内存的可用空间，这可能会影响其他组件的运行。所以，在改动该参数时请务必谨慎。