# TuGraph RESTful API

> This document describes how to call the Rest API of TuGrpah.

## 1.Introduction
TuGraph provides HTTP RESTful APIs, which allow users to access TuGraph servers through HTTP requests remotely.

This document specifiers the TuGraph HTTP RESTful API.

## 2.Request And Response Format
Tugraph HTTP Server receives requests in json format，After authentication, fields in the request are extracted, the request is processed according to the defined interface logic, and the response in json format is returned.

### 2.1.Standard Response Format
Each response is returned in the standard response format, as follows：

| body parameter  | parameter description  | parameter type | necessary |
|--------------|------------------------|----------|-----------|
| errorCode    | error code             | int      | yes       |
| success      | Whether the request was successful | int      | yes       |
| errorMessage | error message          | string   | yes         |
| data         | the response information returned when the request is successful | json string | yes         |

### 2.2. Request Type

#### 2.2.1. User Login
The user sends the login request to the server with the user name and password. After successful login, the client receives a signed token (the Json Web Token) and a Boolean variable (default_password) to determine whether it is the default password. The jwt token stored by the client and added to the Authorization domain of the request header in subsequent requests. If the login fails, you will receive the Authentication failed error.

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

| body parameter  | parameter description | parameter type  | necessary       |
| ------- |-----------------------|-------|------------|
| userName   | name of the user      | string   | yes          |
| password   | password of the user  | string | yes          |

- **RESPONSE**:
If successful, the success field in the returned response message will be set to 00 and the token will be included in data

| body parameter  | parameter description  | parameter type   | necessary |
| ------- |-------|--------|------|
| authorization   | token | string | yes  |
| default_password  | whether the password is the default password | bool | yes  |

**Example request.**

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

#### 2.2.2. User Logout
When a user logs out, the authenticated token is deleted. and the user needs to log in again to obtain a new token when sending subsequent requests.

- **URI**:     /logout
- **METHOD**:  POST
- **REQUEST**:
The http request header carries the token returned by login interface, and the body has no parameters

- **RESPONSE**:
If successful, the success field in the returned response message will be set to 00, and data is empty

#### 2.2.3. Refresh Token
If the delivered token becomes invalid, you need to invoke this interface for re-authentication. The token is valid within one hour after the first login and needs to be refreshed

- **URI**:     /refresh
- **METHOD**:  POST
- **REQUEST**:
The http request header carries the token returned by login interface, and the body has no parameters

- **RESPONSE**:
If successful, the success field in the returned response message will be set to 00, and the token will be included in data

| body parameter  | parameter description | parameter type | necessary       |
| ------- |------|----------------|------------|
| authorization   | token  | string         | yes          |

#### 2.2.4. Call Cypher
User manipulation of data and models in tugraph requires calling the cypher interface and is initiated through the standard cypher query language

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

| body parameter  | parameter description | parameter type | necessary |
| ------- |------------------|---------|-----------|
| graph   | the name of the subgraph to be queried | string  | yes       |
| script   | query statement  | string  | yes         |

- **RESPONSE**:
If successful, the success field in the returned response message will be set to 00, and the query results will be included in data

| body parameter  | parameter description | parameter type | necessary    |
| ------- |------|----------------|------------|
| result   | query results | json string    | yes          |

**Example request.**

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

#### 2.2.5. Upload File
This interface is used to upload local files to the TuGraph machine. You can upload text/binary files, large files, and small files. For large files, the client must split the files, and each file fragment must not be larger than 1MB. Parameters Begin-Pos and Size correspond to the offset and fragment size of this fragment in the complete file. The parameter must be placed in the header of the http request, and the request body contains only the file fragment content. The request header of this interface contains more than token parameters

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

| header parameter | parameter description                | parameter type | necessary |
|------------------|--------------------------------------|---------|-------|
| File-Name        | the name of the file                 | string  | yes   |
| Begin-Pos        | Offset of the start position of the current file fragment within the file | string  | yes   |
| Size             | the current file fragment size       | string | yes   |

- **RESPONSE**:
If successful, the success field in the returned response message will be set to 00

#### 2.2.6. Check File
this interface is used to check the correctness of uploaded files. If the check succeeds, the system returns a success message when the same file is uploaded again

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

| body parameter  | parameter description       | parameter type | necessary |
| ------- |-----------------------------|----------------|-----------|
| fileName   | the name of the file        | string         | yes       |
| checkSum   | the checksum of the file    | string  | yes when flag set to "1" |
| fileSize   | the size of the file        | string  | yes when flag set to "2" |
| flag   | If flag is "1", check md5. If flag is "2"，check file size | string  | yes       |

- **RESPONSE**:
If successful, the success field in the returned response message will be set to 00

| body parameter  | parameter description | parameter type | necessary |
| ------- |------|------|------|
| pass   | true on success, false otherwise | bool | yes  |

**Example request.**

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

#### 2.2.7. Delete Cached File
The admin user can delete all the files uploaded by anyone. Other users can delete their own files. You can delete a file with a specified name, a file uploaded by a specified user, or all files

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

| body parameter  | parameter description | parameter type  | necessary |
| ------- |-----------------------|--------|--------|
| fileName   | the name of the file  | string | yes when flag set to "0" |
| userName   | the name of the user  | string | yes when flag set to "1" |
| flag   | When flag is set to 0, the file specified by fileName is deleted; when flag is set to 1, all files uploaded by userName are deleted; when flag is set to 2, all files are deleted | string | yes    |

- **RESPONSE**:
If successful, the success field in the returned response message will be set to 00

**Example request.**

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

#### 2.2.8. Import Schema
This interface can create a schema model based on the schema information specified by description parameter. For details about the schema format, refer to data-import.md

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

| body parameter  | parameter description | parameter type | necessary |
| ------- |-----------------------|----------------|-----------|
| graph   | name of the subgraph  | string         | yes       |
| description   | schema infomation     | json string    | yes         |

- **RESPONSE**:
  If successful, the success field in the returned response message will be set to 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. Import Data
This interface allows users to specify uploaded and verified files as data files and import them to the subgraph specified by the graph parameter. The import process is asynchronous, and the server returns a task id after receiving the import request

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

| body parameter  | parameter description     | parameter type | necessary |
| ------- |---------------------------|--------|-----|
| graph   | name of the subgraph      | string | yes |
| schema   | schema infomation         | json string | yes |
| delimiter   | column delimiter          | string | yes |
| continueOnError   | Whether to skip the error and continue when an error occurs | boolean | no  |
| skipPackages   | number of packets skipped | string | no  |
| taskId   | used to restart the failed task | string | no  |
| flag   | If flag is set to 1, the data file is deleted after the import is successful | string | no  |
| other   | other parameter           | string | no  |

- **RESPONSE**:
  If successful, the success field in the returned response message will be set to 00

| body parameter  | parameter description                 | parameter type   | necessary       |
| ------- |---------------------------------------|--------|------------|
| taskId   | task id is used to find a import task | string | yes          |

**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. Import Progress Query
This interface is used to query the execution progress of a import task

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

| body parameter  | parameter description                     | parameter type    | necessary |
| ------- |-------------------------------------------|---------|----|
| taskId   | task id returned by import_data interface | string | 是 |

- **RESPONSE**:
  If successful, the success field in the returned response message will be set to 00

| body parameter  | parameter description                | parameter type | necessary |
| ------- |--------------------------------------|----------------|-----------|
| success   | 	whether import is successful        | boolean        | yes       |
| reason   | 	reason of the import failure        | string         | yes if success is false      |
| progress   | 	import progress at the current time | string         | yes       |

**Example request.**

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