REST API¶

Caution

REST API 为预览功能，仅供评估和测试使用，不建议用于生产环境。

开发人员可通过 HTTP 请求调用悦数图数据库开发版提供的 REST API。REST API 的设计简单直观，支持创建图、管理点和边、执行查询以及获取系统指标等多种操作。

需要从配置连接到返回应用 JSON 的完整流程，请参见使用 REST API 构建查询服务。

接口地址¶

接口地址的结构如下：{protocol}://{host}:{port}/{endpoint}，其中：

{protocol}：通信协议。有效值为http或https。默认值为http。
{host}：运行 Graph 服务的开发机主机名或 IP 地址。客户端与 Docker 在同一台开发机时，可以使用127.0.0.1；从其他电脑访问时，使用开发机的 IP 地址。有关部署方法，请参见快速开始。
{port}：指定通信协议下，Graph 服务运行的端口号。默认值为19669。
{endpoint}：要访问的 API 端点。例如，/gql。更多信息，请参见端点。

认证¶

REST API 使用 JWT（JSON Web Token）身份验证来保护端点。您必须先通过端点/auth获取 JWT 令牌，并在后续请求中将令牌包含在Authorization标头中。

例如，可以向端点/auth发送如下 POST 请求来请求 JWT 令牌：

curl -X POST \
  http://localhost:19669/auth \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "your_username", 
  "password": "your_password" 
}'

其中，your_username和your_password须替换为访问 Graph 服务所需的用户名和密码。

若认证成功，将返回如下包含 JWT 令牌的响应：

{
  "code": "00000",
  "message": "",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

从认证响应的data.token字段中获取 JWT 令牌。访问需要认证的端点时，使用 Bearer 认证方案，将令牌添加到Authorization请求头中。例如：

TOKEN='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

curl -X POST \
  http://localhost:19669/gql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "gql": "SHOW GRAPHS"
}'

端点/auth、/api-docs、/health、/info和/metrics无需认证。访问其他端点时，需要提供有效的 JWT 令牌。

请求结构¶

每个 REST API 请求必须构建为 HTTP 请求，并包含以下组件：

HTTP 方法：例如 GET、POST、PATCH 或 DELETE。
HTTP 标头：包含Content-Type、Authorization和其他自定义标头。
接口地址：完整的接口地址。
路径参数：包含在 URL 路径中的参数，例如/graphs/{graphName}。
查询参数：附加到 URL 末尾的可选参数，可用来过滤或修改请求。例如，?edgeType=FOLLOWS&srcId=1&dstId=2。
请求体：以 JSON 格式发送的请求负载。在 POST 和 PATCH 请求中，请求体是必填的。

响应结构¶

每个 API 响应通常包括 HTTP 状态码、响应标头和 JSON 格式的响应体。响应体通常包含以下字段：

code：操作的状态码。排查失败请求时，请同时记录 HTTP 状态码、code和message。
message：操作的描述或结果。
data：操作返回的实际数据（若有）。
summary：操作的摘要，例如受影响的点和边的数量（若有）。

端点¶

本节介绍 REST API 的可用端点及其功能。

端点	HTTP 方法	描述
`/auth`	POST	认证用户并获取 JWT 令牌。
`/signout`	POST	登出用户并使 JWT 令牌失效。
`/api-docs`	GET	获取支持动态交互的 API 参考文档。
`/health`	GET	获取 Graph 服务的健康状态。
`/info`	GET	获取悦数图数据库开发版的基本信息，例如版本和构建信息。
`/metrics`	GET	获取系统运行指标。
`/graphtypes`	GET	获取所有图类型。
	POST	创建图类型。
`/graphtypes/{name}`	GET	获取指定图类型。
	PATCH	修改指定图类型。
	DELETE	删除指定图类型。
`/graphs`	GET	获取所有图。
	POST	创建图。
`/graphs/{name}`	GET	获取指定图。
	PATCH	重命名指定图。
	DELETE	删除指定图。
`/graphs/{graphName}/nodes`	GET	获取指定图中的所有点，或根据单个属性获取特定点。
	POST	向指定图中插入点。
`/graphs/{graphName}/nodes/{id}`	GET	获取指定 ID 的点。
	PATCH	更新指定 ID 的点。
	DELETE	删除指定 ID 的点。
`/graphs/{graphName}/edges`	GET	获取指定图中的所有边。
	PATCH	基于起始点和目标点的 ID 或主键更新边。
	POST	基于起始点和目标点的 ID 或主键向指定图中插入边。
	DELETE	基于起始点和目标点 ID 删除边。
`/procedures`	GET	获取所有过程。
`/procedures/{name}`	GET	获取指定过程。
	DELETE	删除指定过程。
`/procedures/{name}/call`	POST	调用指定过程。
`/gql`	POST	执行 GQL 查询。
`/sessions/{sessionId}/query`	DELETE	终止由`sessionId`指定的会话中的查询。

Note

关于各个端点的详细信息，包括请求和响应参数，请通过端点/api-docs查阅 API 参考文档。

示例¶

以下示例演示如何使用 REST API 执行常见操作。

创建图类型¶

curl -X POST \
  http://localhost:19669/graphtypes \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "name": "test_graph_type",
  "ifNotExists": true,
  "nodeTypes": [
    {
      "name": "Person",
      "labels": [
        "Person"
      ],
      "props": [
        {
          "name": "id",
          "type": "int",
          "primaryKey": true
        },
        {
          "name": "name",
          "type": "string",
          "notNull": false
        },
        {
          "name": "age",
          "type": "int",
          "nullable": true
        }
      ]
    },
    {
      "name": "City",
      "labels": [
        "City"
      ],
      "props": [
        {
          "name": "zipcode",
          "type": "string",
          "notNull": false
        },
        {
          "name": "name",
          "type": "string",
          "notNull": false
        }
      ],
      "primaryKey": [
        "zipcode",
        "name"
      ]
    }
  ],
  "edgeTypes": [
    {
      "name": "LIVES_IN",
      "direction": "PointingLeft",
      "srcNodeType": "Person",
      "dstNodeType": "City",
      "labels": [
        "LIVES"
      ],
      "props": [
        {
          "name": "start_time",
          "type": "datetime",
          "notNull": true
        }
      ],
      "multiEdgeKey": [
        "start_time"
      ]
    }
  ]
}'

创建图¶

curl -X POST \
  http://localhost:19669/graphs \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "name": "test_graph",
  "graphType": "test_graph_type",
  "ifNotExists": true
}'

往图中插入点¶

curl -X POST \
  http://localhost:19669/graphs/test_graph/nodes \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "nodeType": "Person",
  "onConflict": "replace",
  "nodes": [
    {"id": 1, "name": "p1"},
    {"id": 2, "name": "p2"}
  ]
}'

查询图中的点¶

curl -X POST \
  http://localhost:19669/gql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{ "gql": "USE test_graph MATCH (v:Person) RETURN v LIMIT 10" }'