# TuGraph-Restful-Server

> TuGraph Restful Server 强依赖 TuGraph，Restful Server 与 Tugraph 共存

## 1.TuGraph-Restful-Server 简介
TuGraph Restful Server 使用brpc框架支持的http协议，提供restful接口查询功能，在实现中，restful server 与rpc server 使用同一个端口。目前restful接口提供文件上传，数据导入，导入进度查询，cypher查询，文件删除等功能

## 2.启动 TuGraph-Restful-Server
需要在启动Tugraph时设置enable_rpc参数为true的方式，正常启动TuGraph

## 3.连接 TuGraph-Restful-Server
TuGraph正常启动后，Restful Server 将监听在rpc_port上， 通过访问 http://${ip}:${rpc_port}/LGraphHttpService/Query/ url可以链接到TuGraph

## 4.数据格式
客户端与服务端数据交互的格式是 JSON。在发送请求时，请将发送数据的请求的报头设置为 `Accept:application/json, Content-Type:application/json`。
例如在创建一个点时，请求报头包含以下内容：

```
    Accept: application/json; charset=UTF-8
    Content-Type: application/json
    server_version: 12
```

## 5.返回值

通用返回格式

|  body参数  | 参数说明  |  参数类型  |  是否必填  |
|:--------:|:-----:|:------:| :-----: |
| errorCode |  状态码  |  字符串  |  是  |
| errorMessage | 错误信息  |  字符串  |  是  |
| data | 返回的数据 |  字符串  |  是  |

TuGraph 返回的 HTTP 状态码包含以下四种：

- 200 OK: 操作成功
- 400 Bad Request: 输入有误，例如 URI 错误，或者请求中的 JSON 参数错误
- 401 Unauthorized: 未通过鉴权认证，例如用户名密码错误，token超过有效期等
- 500 Internal Server Error: 服务器端错误
  当操作成功时，返回的 data 中包含操作的返回值。
  当发生输入错误或者服务器错误时，返回的 errorMessage 中包含错误提示。

## 6.URI格式

| URI               | 说明                 |
|-------------------|--------------------|
| /cypher           | 执行cypher查询请求       |
| /refresh          | 刷新token请求          |
| /login            | 用户登陆请求             |
| /logout           | 用户登出请求             |
| /upload_files     | 上传文件请求             |
| /clear_cache      | 清理用户上传文件请求         |
| /check_file       | 文件认证请求             |
| /import_data      | 数据导入请求             |
| /import_progress  | 导入进度查询请求           |
| /import_schema    | 批量创建schema请求       |

## 7.接口
### 7.1 用户登陆
用于用户第一次与服务端通信时的鉴权操作，请求报文在 http body 中携带用户名和密码，响应报文在 http body 中会返回一个带有有效期的token，后续请求中需要在http header中携带该token作为凭证
#### 7.1.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/login
#### 7.1.2 REQUEST
|  body参数  |  参数说明  |  参数类型  |  是否必填  |
|:--------:|:------:|:------:| :-----: |
 | userName |  用户名  |  字符串  |  是  |
 | password |   密码   |  字符串  |  是  |
#### 7.1.3 RESPONSE
|    body参数     | 参数说明  |  参数类型  |  是否必填  |
|:-------------:|:-----:|:------:| :-----: |
| authorization | token |  字符串  |  是  |

### 7.2 刷新token
token到期后将无法使用此token与服务端正常通信，需要获取新的token作为后续请求的凭证，请求报文在http header中携带旧的token，响应报文在http body中返回新的token
#### 7.2.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/refresh
#### 7.2.2 REQUEST
|   header参数    |  参数说明   |  参数类型  |  是否必填  |
|:-------------:|:-------:|:------:| :-----: |
| Authorization | 旧的token |  字符串  |  是  |

#### 7.2.3 RESPONSE
|    body参数     |  参数说明   |  参数类型  |  是否必填  |
|:-------------:|:-------:|:------:| :-----: |
| authorization | 新的token |  字符串  |  是  |

### 7.3 用户登出
用户不再需要与服务端进行通信时，需要请求登出接口，释放自己的token。请求报文在http header中携带旧的token，如果拿到返回errorCode为200的响应报文即为正常登出
#### 7.3.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/logout
#### 7.3.2 REQUEST
|   header参数    |  参数说明   |  参数类型  |  是否必填  |
|:-------------:|:-------:|:------:| :-----: |
| Authorization | 旧的token |  字符串  |  是  |

### 7.4 执行cypher查询请求
用户通过此类请求发cypher给server端执行并获取执行结果，请求报文在http body 中将执行的cypher语句和目标子图发送给server，server执行完成后在响应报文的http body中返回执行结果
#### 7.4.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/cypher

#### 7.4.2 REQUEST
| body参数 |    参数说明    |  参数类型  |  是否必填  |
|:------:|:----------:|:------:| :-----: |
| graph  |   查询目标子图   |  字符串  |  是  |
| script | cypher查询语句 |  字符串  |  是  |

#### 7.4.3 RESPONSE
|    body参数     |  参数说明   |  参数类型  |  是否必填  |
|:-------------:|:-------:|:------:| :-----: |
| result | 返回结果 |  字符串  |  是  |

### 7.5 上传文件请求
用户通过此类请求向server发送文件，可以对文件进行分片，分片大小不大于1MB，支持多线程乱序发送，请求报文在http header 中包含文件名，第一字节内容在文件中的偏移和分片大小，在body中包含文件内容，server收到请求后将验证分片大小是否与分片内容一致，一致时将文件分段写入文件。不一致时将返回errorCode为400的响应
#### 7.5.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/upload_files

#### 7.5.2 REQUEST
| header参数  |    参数说明    |  参数类型  |  是否必填  |
|:---------:|:----------:|:------:| :-----: |
| File-Name |   文件名   |  字符串  |  是  |
| Begin-Pos | 开始位置在文件内的偏移 |  字符串  |  是  |
|   Size    | 文件分片大小 |  字符串  |  是  |
|  body参数   |  参数说明   |  参数类型  |  是否必填  |
|     -     | 文件内容 |  字符串  |  是  |

### 7.6 文件认证请求
用户通过此类请求验证发送到server端的文件是否与期望一致，server端使用两种验证方式，md5值和文件长度，目前已支持文件长度验证。
#### 7.6.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/check_file
#### 7.6.2 REQUEST
|  body参数  |          参数说明           |  参数类型  |  是否必填  |
|:--------:|:-----------------------:|:------:| :-----: |
| fileName |           文件名           |  字符串  |  是  |
| checkSum |        文件对应md5值         |  字符串  |  否  |
| fileSize |       文件长度(以字节计算)       |  字符串  |  否  |
| flag | 标记位，为1时校验md5值，为2时校验文件长度 |  字符串  |  是  |

#### 7.6.3 RESPONSE
|    body参数     |  参数说明   |  参数类型  |  是否必填  |
|:-------------:|:-------:|:------:| :-----: |
| pass | 检查成功为true，否则为false |  bool  |  是  |

### 7.7 批量创建schema请求
用户通过此类请求批量创建schema，请求报文在http body 中将创建schema的目标子图和schema信息发送给server，如果拿到返回errorCode为200的响应报文即为正常创建
#### 7.7.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/import_schema
#### 7.7.2 REQUEST
|  body参数  |    参数说明    |  参数类型  |  是否必填  |
|:--------:|:----------:|:------:| :-----: |
| graph |   创建目标子图   |  字符串  |  是  |
| schema | schema描述信息 |  字符串  |  是  |

### 7.8 数据导入请求
用户通过此类请求导入已经上传的数据文件。导入不论成功或失败，都将删除已上传文件。数据导入请求在server中实现为一个异步任务，响应返回并不意味着导入已完成，返回的是任务id，后续可以通过此任务id查询导入进度
#### 7.8.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/import_data
#### 7.8.2 REQUEST
|  body参数  |          参数说明           |  参数类型  | 是否必填 |
|:--------:|:-----------------------:|:------:|:----:|
| graph |         导入目标子图          |  字符串  |  是   |
| schema |       导入schema描述        | json字符串  |  是   |
| delimiter |           分隔符           |  字符串  |  是   |
| continueOnError |     单行数据出错是否跳过错误并继续     |  boolean  |  否   |
| skipPackages |         跳过的包个数          |  字符串  |  否   |
| taskId |  任务id   |  字符串  |  否   |
| other | 其他参数 |  json字符串  |  否   |

#### 7.8.3 RESPONSE
|    body参数     |  参数说明   |  参数类型  |  是否必填  |
|:-------------:|:-------:|:------:| :-----: |
| taskId | 任务编号 |  字符串  |  是  |

### 7.9 清理用户上传文件请求
用户通过此类请求清理已经上传的文件，如果拿到返回errorCode为200的响应报文即为正常清理
#### 7.9.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/clear_cache
#### 7.9.2 REQUEST
|  body参数  |    参数说明    |  参数类型  |  是否必填  |
|:--------:|:----------:|:------:| :-----: |
| fileName |    文件名称    |  字符串  |  否  |
| userName |    用户名称    |  字符串  |  否  |
| flag | 标记位， flag = 0时删除fileName指定文件, flag = 1时删除userName指定用户已经上传的所有文件， flag = 2时删除所有用户上传的文件 |  字符串  |  是  |

### 7.10. 导入进度查询请求
用户通过此类请求获得导入任务的状态
#### 7.10.1 URL
http://${ip}:${rpc_port}/LGraphHttpService/Query/import_progress
#### 7.10.2 REQUEST
|  body参数  |          参数说明           |  参数类型  |  是否必填  |
|:--------:|:-----------------------:|:------:| :-----: |
| taskId |           任务编号           |  字符串  |  是  |

#### 7.10.3 RESPONSE
| body参数 |                  参数说明                   |  参数类型  |  是否必填  |
|:------:|:---------------------------------------:|:------:| :-----: |
| state  | 状态标记，为0表示准备导入，为1表示导入中，为2表示导入成功，为3表示导入失败 |  字符串  |  是  |
|  progress  |             导入进度，state为1时包含             |  字符串  |  否  |
|  reason  |             失败原因，state为3时包含             |  字符串  |  否  |