# 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参数 | 参数说明 | 参数类型  | 是否必填       |
| ------ |------|-------|------------|
| user   | 用户名  | 字符串类型   | 是          |
| password | 用户密码 | 字符串类型 | 是          |

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

| body参数          | 参数说明           | 参数类型   |
|------------------|--------------------|------------|
| jwt              | 令牌               | 字符串类型 |
| is_admin         | 是否是admin用户    | 布尔类型   |
| default_password  | 默认密码           | 布尔类型   |

**Example request.**

```
    {"user" : "admin", "password" : "73@TuGraph"}
```

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

- **URI**:     /logout
- **METHOD**:  POST
  - **REQUEST**:
    http request header中携带调用login接口时返回的token，具体填写的字符串是`Bearer ${jwt}`，`${jwt}`就是login接口返回的jwt，body中没有参数

| header参数           | 参数说明          | 参数类型   |
|------------------|---------------|------------|
| Authorization              | Bearer ${jwt} | 字符串类型 |

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

| body参数          | 参数说明           | 参数类型   |
|------------------|--------------------|------------|
| is_admin         | 是否是admin用户    | 布尔类型   |

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

- **URI**:     /refresh
- **METHOD**:  POST
- **REQUEST**:
  http request header中携带调用login接口返回的token，具体填写的字符串是`Bearer ${jwt}`，`${jwt}`就是login接口返回的jwt，body中没有参数

| header参数           | 参数说明          | 参数类型   |
|------------------|---------------|------------|
| Authorization              | Bearer ${jwt} | 字符串类型 |

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

| body参数          | 参数说明           | 参数类型   |
|------------------|--------------------|------------|
| jwt              | 令牌               | 字符串类型 |
| is_admin         | 是否是admin用户    | 布尔类型   |

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

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

| header参数           | 参数说明          | 参数类型   |
|------------------|---------------|------------|
| Authorization              | Bearer ${jwt} | 字符串类型 |

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

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

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

**Example request.**

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