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"}