Source: https://dev-docs.yueshu.com.cn/v5.3.2/apis/
Documentation version: v5.3.2

# REST API

Caution

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

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

需要从配置连接到返回应用 JSON 的完整流程，请参见[使用 REST API 构建查询服务](https://dev-docs.yueshu.com.cn/v5.3.2/app-development/rest-api/)。

## 接口地址

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

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

## 认证

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`和其他自定义标头。
- 接口地址：完整的[接口地址](https://dev-docs.yueshu.com.cn/v5.3.2/apis/#_1)。
- 路径参数：包含在 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" }'

````

## 更多信息

[GQL 指南](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/)