# RESTful API

> 此文档主要介绍 TuGrpah 的 Rest API 的调用详情。

## 1.简介
TuGraph 提供遵从 REST 规范的 HTTP API，以供开发者通过 HTTP 请求远程调用 TuGraph 提供的服务。

本文档描述 TuGraph 的 HTTP API 使用方式。

## 2.请求与响应格式
TuGraph HTTP Server 接收json格式的请求，经过鉴权后开始提取请求中的字段，根据定义好的接口逻辑处理请求，并返回json格式的响应。

### 2.1.标准响应格式
每一个响应都以标准响应格式返回，格式如下：

| body参数  | 参数说明         | 参数类型        | 是否必填       |
| ------- |--------------|-------------|------------|
| errorCode   | 业务级错误码       | int类型       | 是          |
| success   | 请求是否成功       | int类型       | 是          |
| errorMessage   | 业务级错误信息      | 字符串类型       | 是          |
| data   | 请求成功时返回的响应信息 | json字符串     | 是          |

### 2.2请求类型

#### 2.2.1. 用户登陆
用户在登陆请求中携带用户名和密码发送到服务端。登录成功会收到带有签名的令牌(Json Web Token)和判断是否为默认密码的布尔型变量，客户端储存该令牌，在后续的请求中将令牌加入请求头的Authorization域中。如果登录失败会收到“Authentication failed”错误。

- **URI**:     /login
- **METHOD**:  POST
- **REQUEST**:

| body参数  | 参数说明 | 参数类型  | 是否必填       |
| ------- |------|-------|------------|
| userName   | 用户名  | 字符串类型   | 是          |
| password   | 用户密码 | 字符串类型 | 是          |

- **RESPONSE**:
如果成功，返回的响应信息中success为00，data中包含令牌

| body参数  | 参数说明 | 参数类型  | 是否必填       |
| ------- |------|-------|------------|
| authorization   | 令牌  | 字符串类型   | 是          |
| default_password  | 默认密码 | 布尔类型 | 是          |

**Example request.**

```
    {"userName" : "test", "password" : "123456"}
```

#### 2.2.2. 用户登出
用户登出，同时删除已经认证的token，用户后续发送请求时，需要重新登陆，并获取新的token。

- **URI**:     /logout
- **METHOD**:  POST
- **REQUEST**:
  http request header中携带调用login接口时返回的token，body中没有参数

- **RESPONSE**:
如果成功，返回的响应信息中success为00，data为空

#### 2.2.3. 身份刷新
已下发的token失效后，需要调用本接口重新认证。后端验证token合法性。token在初次登录后，1小时内有效，过期需要刷新

- **URI**:     /refresh
- **METHOD**:  POST
- **REQUEST**:
  http request header中携带调用login接口时返回的token，body中没有参数

- **RESPONSE**:
  如果成功，返回的响应信息中success为00，data中包含令牌

| body参数  | 参数说明 | 参数类型  | 是否必填       |
| ------- |------|-------|------------|
| authorization   | 令牌  | 字符串类型   | 是          |

#### 2.2.4. 调用cypher
用户对TuGraph的增删改查请求需要调用cypher接口，并通过标准的cypher查询语言发起

- **URI**:     /cypher
- **METHOD**:  POST
- **REQUEST**:

| body参数  | 参数说明     | 参数类型  | 是否必填       |
| ------- |----------|-------|------------|
| graph   | 查询的子图名称  | 字符串类型   | 是          |
| script   | cypher语句 | 字符串类型 | 是          |

- **RESPONSE**:
  如果成功，返回的响应信息中success为00，data中包含查询结果

| body参数  | 参数说明 | 参数类型    | 是否必填       |
| ------- |------|---------|------------|
| result   | 查询结果 | json字符串 | 是          |

**Example request.**

```
    {"script" : "Match (n) return n", "graph" : "default"}
```

#### 2.2.5. 上传文件
接口用于将本地文件上传至TuGraph所在机器。可以上传文本文件，二进制文件，可以上传大文件，也可以上传小文件，对于大文件，客户端在上传时应该对文件做切分，每个文件分片不大于1MB，参数Begin-Pos和Size对应本次分片在完整文件中的偏移量与分片大小。参数需要放在http请求的报文头，请求内容对应文件分片内容。本接口请求头不止有token参数

- **URI**:     /upload_file
- **METHOD**:  POST
- **REQUEST**:

| header参数  | 参数说明        | 参数类型             | 是否必填       |
| ------- |-------------|------------------|------------|
| File-Name   | 文件名称        | 字符串类型            | 是          |
| Begin-Pos   | 开始位置在文件内的偏移 | 可以转成size_t类型的字符串 | 是          |
| Size   | 本次请求文件分片大小    | 可以转成size_t类型的字符串 | 是          |

- **RESPONSE**:
  如果成功，返回的响应信息中success为00

#### 2.2.6. 检查文件
本接口用于检查已上传文件正确性，如果成功通过检查，再次上传同一文件时，直接返回成功

- **URI**:     /check_file
- **METHOD**:  POST
- **REQUEST**:

| body参数  | 参数说明           | 参数类型          | 是否必填        |
| ------- |----------------|---------------|-------------|
| fileName   | 文件名称           | 字符串类型         | 是           |
| checkSum   | 文件对应md5值       | 可以转成int类型的字符串 | flag为"1"时必填 |
| fileSize   | 文件长度(以字节计算)    | 可以转成int类型的字符串  | flag为"2"时必填 |
| flag   | 标记位，flag为1时校验md5。flag为2时校验文件长度 | 可以转成int类型的字符串         | 是           |

- **RESPONSE**:
  如果成功，返回的响应信息中success为00

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

**Example request.**

```
{"fileName" : "test.csv", "checkSum" : "$MD5", "flag" : “1”}
```

#### 2.2.7. 清理缓存文件
admin用户可以删除所有用户上传的文件，其他用户可以删除自己的上传的文件，可以删除指定名称的文件，指定用户上传的文件，也可以删除所有文件

- **URI**:     /clear_cache
- **METHOD**:  POST
- **REQUEST**:

| body参数  | 参数说明        | 参数类型          | 是否必填        |
| ------- |-------------|---------------|-------------|
| fileName   | 文件名称        | 字符串类型         | flag为"0"时必填 |
| userName   | 用户名称        | 字符串类型 | flag为"1"时必填 |
| flag   | 标记位，flag为0时删除fileName指定文件, flag为1时删除userName指定用户已经上传的所有文件，flag为2时删除所有用户上传的文件 | 可以转成int类型的字符串         | 是           |

- **RESPONSE**:
  如果成功，返回中success为00

**Example request.**

```
{"fileName" : "test.csv", "userName" : "test", "flag" : “1”}
```

#### 2.2.8. 导入schema
本接口可以根据用户指定的schema信息创建schema模型，schema的详细格式信息请参考data-import.md

- **URI**:     /import_schema
- **METHOD**:  POST
- **REQUEST**:

| body参数  | 参数说明       | 参数类型          | 是否必填        |
| ------- |------------|---------------|-------------|
| graph   | 子图名称       | 字符串         | 是           |
| description   | schema描述信息 | json字符串 | 是 |

- **RESPONSE**:
  如果成功，返回中success为00

**Example request.**

```
{
	"graph": "test_graph",
	"description": {
		"schema": [{
			"label": "Person",
			"type": "VERTEX",
			"primary": "name",
			"properties": [{
				"name": "name",
				"type": "STRING"
			}, {
				"name": "birthyear",
				"type": "INT16",
				"optional": true
			}, {
				"name": "phone",
				"type": "INT16",
				"unique": true,
				"index": true
			}]
		}, {
			"label": "City",
			"type": "VERTEX",
			"primary": "name",
			"properties": [{
				"name": "name",
				"type": "STRING"
			}]
		}, {
			"label": "Film",
			"type": "VERTEX",
			"primary": "title",
			"properties": [{
				"name": "title",
				"type": "STRING"
			}]
		}, {
			"label": "HAS_CHILD",
			"type": "EDGE"
		}, {
			"label": "MARRIED",
			"type": "EDGE"
		}, {
			"label": "BORN_IN",
			"type": "EDGE",
			"properties": [{
				"name": "weight",
				"type": "FLOAT",
				"optional": true
			}]
		}, {
			"label": "DIRECTED",
			"type": "EDGE"
		}, {
			"label": "WROTE_MUSIC_FOR",
			"type": "EDGE"
		}, {
			"label": "ACTED_IN",
			"type": "EDGE",
			"properties": [{
				"name": "charactername",
				"type": "STRING"
			}]
		}, {
			"label": "PLAY_IN",
			"type": "EDGE",
			"properties": [{
				"name": "role",
				"type": "STRING",
				"optional": true
			}],
			"constraints": [
				["Person", "Film"]
			]
		}]
	}
}
```

#### 2.2.9. 导入数据
本接口允许用户指定已经通过上传，校验的文件作为数据文件，按照schema参数描述的配置信息，导入到graph参数指定的子图中。导入过程是异步的，server在接收到导入请求后，返回一个任务id

- **URI**:     /import_data
- **METHOD**:  POST
- **REQUEST**:

| body参数  | 参数说明  | 参数类型    | 是否必填 |
| ------- |-------|---------|----|
| graph   | 子图名称  | 字符串类型   | 是  |
| schema   | 导入schema描述 | json字符串 | 是  |
| delimiter   | 分隔符   | 字符串类型   | 是  |
| continueOnError   | 单行数据出错是否跳过错误并继续 | boolean类型 | 否  |
| skipPackages   | 跳过的包个数 | 可以转成int类型的字符串 | 否  |
| taskId   | 任务id，用于重启出错的任务 | 字符串类型 | 否 |
| flag   | 标记位，flag为1时导入成功将删除数据文件 | 可以转成int类型的字符串 | 否 |
| other   | 其他参数 | 可以转成int类型的字符串 | 否  |

- **RESPONSE**:
  如果成功，返回的响应信息中success为00

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

**Example request.**

```
{
   "graph": "default",         //导入的子图名称
   "delimiter": ",",						//数据分隔符
   "continueOnError": true,		//遇到错误时是否跳过错误数据并继续导入
   "skipPackages": “0”,					//跳过的包个数
   "flag" : "1",
	 "schema": {
		"files": [{
			"DST_ID": "Film",				//终点label类型
			"SRC_ID": "Person",			//起点label类型
			"columns": [						//数据格式说明
				"SRC_ID",							//起点id
				"DST_ID",							//终点id
                "SKIP",								//表示跳过此列数据
				"charactername"				//属性名称
			],
			"format": "CSV",				//数据文件格式类型,支持csv和json
			"path": "acted_in.csv",	//数据文件名称
			"header": 0, 						//数据从第几行开始
			"label": "ACTED_IN"			//边的类型
		}]
	}
}
```

#### 2.2.10. 导入进度查询
本接口用于查询导入任务的执行进度

- **URI**:     /import_progress
- **METHOD**:  POST
- **REQUEST**:

| body参数  | 参数说明                 | 参数类型    | 是否必填 |
| ------- |----------------------|---------|----|
| taskId   | import_data接口返回的任务id | 字符串类型 | 是 |
- **RESPONSE**:
  如果成功，返回的响应信息中success为00

| body参数  | 参数说明    | 参数类型             | 是否必填    |
| ------- |---------|------------------|---------|
| success   | 	是否成功导入 | boolean类型        | 是       |
| reason   | 	导入失败原因 | 字符串类型            | success为false时必填 |
| progress   | 	当前导入进度 | 可以转成double类型的字符串 | 是       |

**Example request.**

```
{"taskId" : "$taskId"}
```