TuGraph RESTful API Legacy

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.

:warning: All the other RESTful APIs excluding the three below will be deprived after 4/30/2023.

Login
Query
Store Procedures

2.Protocols And Data Format

2.1.Protocols

Both HTTP and HTTPS protocols are supported by TuGraph. The system uses HTTP protocol by default. To use HTTPS, the ssl_auth option should be set to true in the DB configuration.

2.2.Request

TuGraph supports HTTP GET/POST/PUT/DELETE requests, in which:

GET requests are used for read-only requests, such as getting vertex properties, edge properties, etc.
POST requests are used to create entities, submit Cypher, and to manage and call stored procedures;
PUT requests are used to modify existing entities, for example, to modify vertex properties, edge properties, etc.
DELETE requests are used to delete existing entities, such as vertices, edges, etc.

In high-availability mode, users can set ServerVersion in the request header to make sure the request is never served with an outdated version. The current ServerVersion can be obtained from the header returned by the server.

2.3.Response

TuGraph returns the following HTTP status codes:

200 OK: operation is successful.
307 Temporary Redirect: the operation is redirected, typically in high-availability mode, to the master.
400 Bad Request: incorrect input, such as URI error, or invalid parameters.
500 Internal Server Error: server error.

When the operation is successful, the JSON response contains the return value of the operation. When the operation is redirected, the location field in the returned HTTP header contains the redirect destination address. When an input error or server error occurs, the JSON response contains a error_message field that describes the error.

In high-availability mode, the server will set server_version field in the header to inform the client of the data version of the current server. When clients switch between several different servers, this version number guarantees that the client will not read from an outdated server.

2.4.Data Format

The server and clients exchange data in JSON format. When sending a request, the header of the HTTP request should be set with Accept:application/json, Content-Type:app/json. For example, to create a new vertex, the request header should look like the following:

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

2.5.URI Format

TuGraph REST API provides access to: web visualization, login, db info, label, index, node, relationship, cypher, task, cpp_plugin, and python_plugin. The URI format used for each function is as follows:

URI	Description
/web	web visualization
/cypher	cypher request
/acl	access control
/user	user management
/login	user login
/info	database status and information
/task	task management
/db	subgraph management

For each subgraph, the following interfaces are provided:

URI	Description
/db	create, modify, and delete subgraph
/db/{graph_name}/node	vertex operations
/db/{graph_name}/relationship	edge operations
/db/{graph_name}/label	label-related operations
/db/{graph_name}/index	index-related operations
/db/{graph_name}/cypher	subgraph-specific cypher operation
/db/{graph_name}/cpp_plugin	C++ plugin(stored procedure)
/db/{graph_name}/python_plugin	Python plugin(stored procedure)
/db/{graph_name}/import	online import
/db/{graph_name}/misc	other operations

3.Login

The system creates an administrator by default, whose username is admin and password is 73@TuGraph. For security reasons, please remember to change your password after first starting the server.

3.1.User Login

TuGraph provides JWT-based user authentication. To log in to the server, the REST client should send a login request containing a username and password. Upon success, the client will receive a signed token in the form of a Json Web Token (JWT) and a Boolean variable (default_password) to determine whether it is the default password. The jwt token should be stored by the client and used for each subsequent request.

URI: /login
METHOD: POST
REQUEST:

Field	Description	Type
user	username	String
password	password	String

RESPONSE:

Field	Description	Type
jwt	token	String
default_password	whether it is the default password	Bool

Example Request:

    • POST http://localhost:7070/login
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "user":"admin",
      "password":"73@TuGraph"
    }

Example Response:

    • 200: OK
    Output:
    {
        "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek",
        "default_password": true
    }

3.2.Token Refresh

After the token expires, the front-end initiates a refresh token interface, and the back-end verifies the validity of the token. If the verification passes, a new token is generated; if the verification fails, status code 401 is returned.

URI: /refresh
METHOD: POST
REQUEST:

Field	Description	Type
Authorization	token	String

RESPONSE:

Field	Description	Type
jwt	token	String

Example Request:

    • POST http://localhost:7070/refresh
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization": "Bearer eyJhbGciOiJIUz32NiIsInR5cCI6IkpXVDJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byj3fYVAH4D88dfTD_zYQ_uAvdizTMek"
    }

Example Response:

    • 200: OK
    Output:
    {
        "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek"
    }

3.3.Modify Token Validity Period

To modify the validity period of Token, three parameters need to be transmitted: jwt, refresh_time and expire_time, among which jwt is used to verify the user’s identity. When refresh_time and expire_time are equal to 0, the validity period is indefinite. When refresh_time exceeds, you need to call the refresh interface to obtain a new Token; When expire_time expires, you need to log in again. (This interface call needs to confirm the security by itself, do not call unless necessary)

URI: /update_token_time
METHOD: POST
REQUEST:

Field	Description	Type
Authorization	token	String
refresh_time	Valid time (deafult set to 0)	Int64
expire_time	Expire time (deafult set to 0)	Int64

RESPONSE: if successful, return status code 200.

Example request.

    • POST http://localhost:7070/update_token_time
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJmbWEuYWkiLCJwYXNzd29yZCI6IjczQFR1R3JhcGgiLCJ1c2VyIjoiYWRtaW4ifQ.o_yb5veSJkuy-ieBp4MqTk-tC1grcKotgVbgNJ0TyTU",
        "refresh_time":0
        "expire_time":0
    }

Example response.

    • 200: OK

3.4.Query Token validity period

To query the validity period of the Token, you need to transmit jwt to verify the user’s identity, and return, refresh_time and expire_time, where refresh_time indicates the refresh time, and you need to call the refresh interface to obtain a new Token when it exceeds; expire_time indicates the expiration time, and you need to log in again when it exceeds.

URI: /get_token_time
METHOD: POST
REQUEST:

Field	Description	Type
Authorization	token	String

RESPONSE: if successful, return “refresh_time” and “expire_time”.

Example request.

    • POST http://localhost:7070/get_token_time
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJmbWEuYWkiLCJwYXNzd29yZCI6IjczQFR1R3JhcGgiLCJ1c2VyIjoiYWRtaW4ifQ.o_yb5veSJkuy-ieBp4MqTk-tC1grcKotgVbgNJ0TyTU",
    }

Example response.

    • 200: OK
    Output:
    {
        "refresh_time":600,
        "expire_time":3600
    }

3.5.Logout

The user logs out and deletes the token at the same time.

URI: /logout
METHOD: POST
REQUEST:

Field	Description	Type
Authorization	token	String

RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/refresh
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "Authorization" : "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJmbWEuYWkiLCJwYXNzd29yZCI6IjczQFR1R3JhcGgiLCJ1c2VyIjoiYWRtaW4ifQ.o_yb5veSJkuy-ieBp4MqTk-tC1grcKotgVbgNJ0TyTU"
    }

Example Response:

    • 200: OK

4.Query

URI format is:

    http://{host}:{port}/cypher

4.1.Call Cypher

URI: /cypher
METHOD: POST
REQUEST:

Field	Description	Type
graph	subgraph name	String
cypher	Cypher query	String

RESPONSE:

Field	Description	Type
result	running results	List
elapsed	running time in seconds	Float
header	header of the results	List
size	number of results	Integer

in which header is a list with each element in the form of:

Field	Description	Type
name	the name of column	String
type	column data type, 0 is scalar, 1 is vertex id, 2 is vector

Example Request:

    • POST http://localhost:7070/cypher
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "graph": "default",
        "script": "MATCH (n) RETURN n,n.name LIMIT 10"
    }

Example Response:

    • 200: OK
    Output:
    {
        "elapsed": 0.001224517822265625,
        "header": [
            {
                "name": "n",
                "type": 1
            },
            {
                "name": "n.name",
                "type": 0
            }
        ]
        "result": [
            [
                0,
                "Rachel Kempson"
            ],
            [
                1,
                "Michael Redgrave"
            ],
            [
                2,
                "Vanessa Redgrave"
            ]
        ],
        "size": 3
    }

4.2.Call Cypher with Parameters

Cypher supports querying with parameters. When a Cypher query with parameters is called, TuGraph caches the execution plan for that query to speed up the following queries of the same kind.

URI: /cypher
METHOD: POST
REQUEST:

Field	Description	Type
graph	subgraph name	String
cypher	Cypher query	String
parameters	parameters	List

RESPONSE:

Same as Call Cypher.

Example Request:

    • POST http://localhost:7070/db/graph1/cypher
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "graph": "default",
      "script": "MATCH (n:Person {name:$param1}) RETURN n.birthyear",
      "parameters": {
        "$param1": "Lindsay Lohan"
      }
    }

Example Response:

    • 200: OK
    Output:
    {
        "elapsed": 0.005886077880859375,
        "header": [
            {
                "name": "n.birthyear",
                "type": 0
            }
        ],
        "result": [
            [
                1986
            ]
        ],
        "size": 1
    }

5.Stored Procedures

URI format is:

    http://{host}:{port}/db/{graph_name}/cpp_plugin|python_plugin

5.1.Create Stored Procedure

URI: /db/{graph_name}/cpp_plugin|python_plugin
METHOD: POST
REQUEST:

Field	Description	Type
name	name of the plugin	String
description	description of the plugin	String
code_base64	code of plugin encoded in base64	String
read_only	whether it is a read-only stored procedure	Bool
code_type	type of plugin code, can be zip/cpp/so for cpp_plugin, while py for python_plugin	String

Note: read-only plugins are more efficient than write plugins. Always specify read-only=true for read-only transactions.

RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db/graph1/cpp_plugin
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        "name" : "echo",
        "description" : "A test plugin that returns the input",
        "code_base64" : "{base64 encoded echo.so}",
        "read_only" : true,
        "code_type" : "zip"
    }

Example Response:

    • 200: OK

5.2.List Stored Procedures

URI: /db/{graph_name}/cpp_plugin|python_plugin
METHOD: GET
RESPONSE: A list in which each element is a plugin description, in the format of:

Field	Description	Type
name	name of the stored procedure	String
description	description of the stored procedure	String
read_only	whether the stored procedure is read-only	Bool

Example Request:

    • GET http://localhost:7070/db/graph1/cpp_plugin
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    Output:
    {
        [
            {
                "description":"adds a vertex label to the db",
                "name":"add_label",
                "read_only":false
            },
            {
                "description": "scans graph and get number of edges",
                "name": "scan_graph",
                "read_only": true
            }
        ]
    }

5.3.Retrieve Stored Procedure Detail

URI: /db/{graph_name}/cpp_plugin|python_plugin/{plugin_name}
METHOD: GET
RESPONSE: Procedure detail, including code, in the format of:

Field	Description	Type
name	Procedure name	String
description	Procedure descrition	String
read_only	Read only or not	Bool
code_base64	存储过程的代码	String, Base64 encoded
code_type	Type of procedue code, can be zip/cpp/so for cpp_plugin, while py for python_plugin	String

Example request.

    • GET http://localhost:7070/db/graph1/cpp_plugin/echo
    • Accept: application/json; charset=UTF-8

Example response.

    • 200: OK
    Output:
    {
        "name" : "echo",
        "description" : "A test plugin that returns the input",
        "code_base64" : "{base64 encoded echo.zip}",
        "read_only" : true,
        "code_type" : "zip"
    }

5.4.Call Stored Procedure

URI: /db/{graph_name}/cpp_plugin|python_plugin/{plugin_name}
METHOD: POST
REQUEST: String input.

Field	Description	Type
data	input data	String
timeout	timeout in seconds, defaults to 0, which means no timeout	Float

RESPONSE:

Field	Description	Type
result	running results	String

Example Request:

    • POST http://localhost:7070/db/graph1/python_plugin/echo
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
        data : "Hello!\n你好！\nKonichiwa!",
        timeout : 0,
        in_process : true
    }

Example Response:

    • 200: OK
    Output:
    {
      "result": "Hello!\n你好！\nKonichiwa!"
    }

5.5.Delete Stored Procedure

URI: /db/{graph_name}/cpp_plugin|python_plugin/{plugin_name}
METHOD: DELETE
RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1/cpp_plugin/example_plugin
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.Deprecated

The APIs below will be removed after 4/30/2023.

6.1.User Management

6.1.1.Add User

Add a new user and set the initial password for the user. Only administrators have permission to add new users. The username can only have letters, numbers, and underscores, and should not begin with a number. The password can contain any character. The username and password have a maximum length of 64 bytes.

URI: /user
METHOD: POST
REQUEST:

Field	Description	Type
user	username	String
password	password	String
is_admin	whether the user is an administrator or not	Bool

RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/user
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek
    Input:
    {
        "user": "USER1",
        "password": "AN_INITIAL_PASSWORD",
        "is_admin": false
    }

Example Response:

    • 200: OK

6.1.2.Change Password

Users can change their own passwords, in which case the original password needs to be verified.

Administrators can change the passwords of any user and promote non-admin users to administrators, or demote administrator users to regular users. When modifying another user’s password, the original password of the user is not needed.

URI: /user/{user_name}
METHOD: PUT
REQUEST:

Field	Description	Type
current_password	user’s current password, if modifying its own password	String
new_password	user’s new password	String
is_admin	should this user be administrator or not, used when promoting or demoting users	Bool

RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/user/user1
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek
    Input:
    {
        "current_password": "THE_CURRENT_PASSWORD"
        "new_password": "A_NEW_PASSWORD"
        "is_admin": true
    }

Example Response:

    • 200: OK

6.1.3.List All Users

List all users of the database. Only administrators are allowed to perform this operation.

URI: /user/
METHOD: GET
RESPONSE: a dictionary of {user_name:is_admin}

Example Request:

    • GET http://localhost:7070/user
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

• 200: OK
Output:
{
    "admin": true,
    "guest1": false
}

6.1.4.Delete User

Delete a user from the DB. Only administrators have permission to do so.

URI: /user/{user_name}
METHOD: DELETE
RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/user/guest1
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

    • 200: OK

6.2.Access Control

TuGraph has four access levels. Different users can have different permissions for each subgraph. The four access levels are as follows:

Access Level	Description
NONE	no access
READ	read-only
WRITE	can read and write vertexes and edges of the subgraph
FULL	full access, including changing metadata (label, index), managing stored procedures and deleting all data in the subgraph

Administrators have full access on all subgraphs, and a newly created non-admin user does not have access for any subgraph. Users who have full access on a subgraph can set the access level for other users on that subgraph.

6.2.1.Query User’s Access Level

URI: /acl/?user={user_name}&graph={graph_name}
METHOD: GET
RESPONSE:

When both user and graph are specified, the user’s access level for the subgraph is returned, such as READ.

When only user is specified, all subgraphs that the user can access (access level not NONE) are returned, as well as the user’s access level on the subgraph.

When only graph is specified, all users who have access level on this graph (excluding administrators, who have implicit FULL access) and their access levels are returned. This operation requires administrator permission.

Example Request:

    • GET http://localhost:7070/acl/?user=user1
    • Accept: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "graph1": "READ",
      "graph2": "WRITE",
      "graph3": "FULL"
    }

6.2.2.Change User’s Access Level

URI: /acl
METHOD: PUT
REQUEST:

Field	Description	Type
user	username	String
graph	subgraph’s name	String
acl	access level	String

RESPONSE: if successful, return status code 200.

Example Request:

    • PUT http://localhost:7070/acl
    • Accept: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek
    Input:
    {
        "user": "user1",
        "graph": "graph1",
        "acl": "FULL"
    }

Example Response:

    • 200: OK

6.2.3.Remove User’s Access Right

This is equivalent to setting access level to NONE.

URI: /acl/?user={user_name}&graph={graph_name}
METHOD: DELETE
RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/acl/?user=user1&graph=graph1
    • Accept: application/json; charset=UTF-8
    • Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiaXNzIjoiZm1hLmFpIiwidXNlcl9pZCI6ImFkbWluIn0.SHaqrjKLaI4byjbEYVAH4D88dOTD_zYQ_uAvdizTMek

Example Response:

    • 200: OK

6.3.Server Status

6.3.1.Modify Server Configuration

Modifying the server configuration will take effect immediately after the configuration modification and will affect all servers. These configurations take precedence over configuration files and command line arguments.

URI: /config
METHOD: PUT

REQUEST:

Field	Description	Type
db_async	Whether to enable asynchronous mode	Bool
optimistic_txn	Whether to use optimistic transaction lock by default	Bool
enable_audit_log	Whether to enable audit logging	Bool

RESPONSE: If successful, return status code 200.

Example request.

    • PUT http://localhost:7070/config
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "db_async": true,
        "enable_audit_log": false
    }

Example response.

    • 200: OK

6.3.2.Current Server Status

URI: /info
METHOD: GET
RESPONSE:

Field	Description	Type
lgraph_version	TuGraph version	String
git_branch	server’s git branch	String
git_commit	server’s git commit version	String
web_commit	web client commit version	String
cpp_id	cpp compiler id	String
cpp_version	cpp compiler version	String
python_version	python lib version	String
cpu	cpu information	Dictionary, format refers CPU Status
disk	disk IO information	Dictionary, format refers Disk Status
memory	memory information	Dictionary, format refers Memory Status
db_space	graph database storage	Dictionary, format refers Graph Database Storage
db_config	graph database configuration	Dictionary, format refers Graph Database Configuration
up_time	database’s online running time	Integer

Example Request:

    • GET http://localhost:7070/info
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "lgraph_version": "1.2.0",
      "git_branch": "master",
      "git_commit": "9e2977d",
      "web_commit": "1e2823d",
      "cpu_id": "GUN",
      "cpu_version": "4.8.5",
      "python_version": "3.2",
      "node": "/node",
      "relationship": "/relationship",
      "cpu": {
        "self": 25,
        "server": 35,
        "unit": "%"
      },
      "disk": {
        "read": 2000,
        "write": 2000,
        "unit": "B/s"
      },
      "memory": {
        "self": 25016,
        "server_avail": 46865636,
        "server_total": 65860552,
        "unit": "KB"
      },
      "db_space": {
        "space": 57344,
        "unit": "B"
      },
      "db_config": {
        "db_async": false,
        "disable_auth": false,
        "enable_ha": false,
        ...
      },
      "up_time": 3235
    }

6.3.3.CPU Status

URI: /info/cpu
METHOD: GET
RESPONSE:

Field	Description	Type
self	TuGraph CPU usage	Integer
server	server’s CPU usage	Integer
unit	metric unit	String

Example Request:

    • GET http://localhost:7070/info/cpu
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "self": 25,
      "server": 35,
      "unit": "%"
    }

6.3.4.Disk Status

URI: /info/disk
METHOD: GET
RESPONSE:

Field	Description	Type
read	server’s disk read rate	Integer
write	server’s disk wrtie rate	Integer
unit	metric unit	String

Example request.

    • GET http://localhost:7070/info/disk
    • Accept: application/json; charset=UTF-8

Example response.

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "read": 2000,
      "write": 2000,
      "unit": "B/s"
    }

6.3.5.Memory Status

URI: /info/memory
METHOD: GET
RESPONSE:

Field	Description	Type
self	TuGraph memory usage	Integer
server_avail	server’s available memory	Integer
server_total	server’s total memory	Integer
unit	metric unit	String

Example Request:

    • GET http://localhost:7070/info/memory
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "self": 25016,
      "server_avail": 46865636,
      "server_total": 65860552,
      "unit": "KB"
    }

6.3.6.Database Size

URI: /info/db_space
METHOD: GET
RESPONSE:

Field	Description	Type
space	total size of the database	Integer
unit	metric unit	String

Example Request:

    • GET http://localhost:7070/info/db_space
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "space": 57344,
      "unit": "B"
    }

6.3.7.DB Configuration

URI: /info/db_config
METHOD: GET
RESPONSE:

Field	Description	Type
async	asynchronous mode	Bool
disable_auth	whether to disable authentication	Bool
enable_ha	whether to enable high-availability mode	Bool
enable_rpc	whether to enable RPC server	Bool
host	bound host address	String
port	port of REST server	Integer
rpc_port	port of RPC server	Integer
thread_limit	limit of available threads for the graph database	Integer
use_ssl	whether to use SSL for authentication	Bool
verbose	verbose level of the output	Integer

Example Request:

    • GET http://localhost:7070/info/db_config
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "async":false,
      "disable_auth":false,
      "enable_ha":false,
      "enable_rpc":false,
      "host":"127.0.0.1",
      "port":7070,
      "rpc_port":9091,
      "thread_limit":0,
      "use_ssl":false,
      "verbose":2
    }

6.3.7.High Availability Server List

Get a list of replication servers. Valid only in high-availability mode.

URI: /info/peers
METHOD: GET
RESPONSE: if successful, return status code 200 and a list of server information, each of server information is formatted as:

Field	Description	Type
rpc_address	server’s RPC address	String
rest_address	server’s REST address	String
state	server state	String

The server state can be MASTER, SLAVE, or OFFLINE.

Example Request:

    • GET http://localhost:7070/info/peers
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      [
          {
              "rest_address":"192.168.1.22:17071",
              "rpc_address":"192.168.1.22:19091",
              "state":"MASTER"
          },
          {
              "rest_address":"192.168.1.22:17072",
              "rpc_address":"192.168.1.22:19092",
              "state":"SLAVE"
          }
      ]
    }

6.3.8.Current Leader Information

Get information of current leader. Valid only in HA mode.

URI: /info/leader
METHOD: GET
RESPONSE: if successful, return status code 200 and the current leader server information, which is formatted as:

Field	Description	Type
rpc_address	server’s RPC address	String
rest_address	server’s REST address	String

Example Request:

    • GET http://localhost:7070/info/leader
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
      "rest_address":"192.168.1.22:17071",
      "rpc_address":"192.168.1.22:19091"
    }

6.3.9.Server Statistics

URI: /info/statistics
METHOD: GET
RESPONSE: if successful, return status code 200 and the current server statistics, which is formatted as:

Field	Description	Type
requests/second	number of requests processed per second	Float
writes/second	number of write requests processed per second	Float
running_tasks	number of requests in progress	Integer
failure_rate	request failure rate	Float

Example Request:

    • GET http://localhost:7070/info/statistics
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "failure_rate": 0.023,
        "requests/second": 122.3,
        "running_tasks": 10,
        "writes/second": 12.4
    }

6.3.10.Get Audit Logs

URI: /info/log/?begin_time={begin_time}&end_time={end_time}&user={user}&num_log={num_log}&descending_order={descending_order}

Field	Description	Type
begin_time	start time of the queried log (required, format YYYY-mm-dd HH:MM:SS)	Timestamp
end_time	end time of the queried log (default is current time, format YYYY-mm-dd HH:MM:SS)	Timestamp
user	the operator of the queried log (administrator can query all users’ logs, ordinary users can only query their own logs)	String
num_log	maximum number of logs to return (default 100)	Integer
descending_order	whether to sort the result in descending order(default is true)	Bool

METHOD: GET
RESPONSE: if successful, return status code 200 and a list of audit logs, each of which is an action log in the format of:

Field	Description	Type
index	the index of the operation	Integer
begin_time	the start time of the operation	String
end_time	the end time of the operation	String
user	the user of the operation	String
graph	the graph of the operation	String
type	the type of the operation	String
read_write	the operation is read operation or write operation	String
success	whether the operation is successful	Bool
content	the content of the operation	String

Example Request:

    • GET http://localhost:7070/info/log/?begin_time=2020-02-17%2015:00:00&end_time=2020-02-20%2012:00:00&user=admin&num_log=100&descending_order=false
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            {
                "begin_time": "2020-02-17 15:27:15",
                "content": "post /login    Successful",
                "end_time": "2020-02-17 15:27:15",
                "graph": "",
                "index": 1,
                "read_write": "read",
                "success": true,
                "type": "Security",
                "user":"admin"
            },
            {
                "begin_time": "2020-02-17 15:27:15",
                "content": "Load plugin : `echo`    Successful",
                "end_time": "2020-02-17 15:27:15",
                "graph": "default",
                "index": 2,
                "read_write": "write",
                "success": true,
                "type": "Plugin",
                "user": "admin"
            },
            ...
        ]
    }

6.4.Task Management

TuGraph tracks long-running tasks such as complex Cypher queries and plugins. Administrators can query currently running tasks through the REST API and choose to abort the queries if necessary.

The URI format for task management is :

    http://{host}:{port}/task/{task_id}

6.4.1.List Running Tasks

URI: /task
METHOD: GET
RESPONSE:

The returned JSON is an array, each of which is formatted as follows:

Field	Description	Type
description	the description of the task	String
time_elapsed	time the task has been executing for, in seconds	Float
task_id	the ID of the task	String

Example Request:

    • GET http://localhost:7070/task
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            {
                "description" : "[CPP_PLUGIN] scan_graph",
                "time_elapsed" : 13.987,
                "task_id" : "3_10"
            },
            {
                "description" : "[CYPHER] MATCH(n) return n",
                "time_elapsed" : 30.887,
                "task_id" : "2_6"
            }
        ]
    }

6.4.2.Abort Task

URI: /task/{task_id}

Where task_id is the task_id returned by GET /task .

METHOD: DELETE
RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/task/3_10
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.5.Subgraph Management

TuGraph supports multiple subgraphs and all subgraphs are completely independent from others. Different subgraphs can have different permissions to different users. Administrators can add, modify and delete subgraphs.

6.5.1.Create New Subgraph

URI: /db
METHOD: POST
REQUEST:

Field	Description	Type
name	the name of subgraph	String
config	the configuration of subgraph	Dictionary, in the format of {{column name 1}:{column value 1},…}

RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "name":"graph1"
        "config" : {
            "max_size_GB":2048,
            "async":True
        }
    }

Example Response:

    • 200: OK

6.5.2.Delete Subgraph

URI: /db/{graph_name}
METHOD: DELETE
RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1

Example Response:

    • 200: OK

6.5.3.List All Subgraphs

URI: /db
METHOD: GET
RESPONSE: The list of all subgraphs.

Example Request:

    • GET http://localhost:7070/db

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "graph1": {
            "max_size_gb":1024,
            "async":false
        }
    }

6.6.Label

TuGraph is a strong-schema database. In each subgraph, each vertex and edge need to have a predefined data format. The data format is determined by Label. Users can use the REST API to add, delete, and query labels and their corresponding data format.

The URI format of the Label operation is

    http://{host}:{port}/db/{graph_name}/label/{type}/{label_name}

Where the {type} can be node or relationship.

6.6.1.Create Label

A label is created with a fixed data format. A label must be defined before any node or relationship can be created with that label.

URI: /db/{graph_name}/label
METHOD: POST
REQUEST:

Field	Description	Type
name	the name of label	String
fields	data column definition	List
is_vertex	whether it is a vertex Label	Bool
primary	vertex primary property	String
edge_constraints	edge constraints	List

primary should be set when is_vertex is true. This field is only available for Vertex, and must be set when creating Vertex.

edge_constraints could be set when is_vertex is false, This field is only available for Edge. This field limits the combination of starting and ending vertex of the edge, for example: [["vertex_label1","vertex_label2"],["vertex_label3","vertex_label4"]], which limits the edge direction can only be from vertex_label1 to vertex_label2 or from vertex_label3 to vertex_label4. If you don’t want to have any constraints, just leave this field unset.

In which fields is an array, in which each element defines a column of data, as follows:

Field	Description	Type
name	the name of the column	String
type	the data type of the column	String, with following types: int8, int16, int32, int64, float, double, string, date, datetime, binary, blob
optional	whether the data can be empty (optional, default is false)	Bool

RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/label
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "name":"Actor",
        "fields": [
                {"name":"uid", "type":"int64", "optional":false},
                {"name":"name", "type":"string", "optional":true}
        ],
        "is_vertex":true,
        "primary" : "uid"
    }

Example Response:

    • 200: OK

6.6.2.List All Labels

URI: /db/{graph_name}/label
METHOD: GET
RESPONSE:

Field	Description	Type
edge	the list of edge labels	List
vertex	the list of vertex labels	List

Example Request:

    • GET http://localhost:7070/db/{graph_name}/label
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "edge": [
            "HAS_CHILD",
            "MARRIED",
            "BORN_IN",
            "DIRECTED",
            "WROTE_MUSIC_FOR",
            "ACTED_IN"
        ],
        "vertex": [
            "Person",
            "City",
            "Film"
        ]
    }

6.6.3.Get Label Data Format

URI: /db/{graph_name}/label/{[node|relationship]}/{label_name}
METHOD: GET
RESPONSE: Data column definition table as a dictionary, in which each key is the column name, and corresponding value is the column definition defined as follows:
Field

Description

Type

optional

whether the column value can be empty

Bool

type

the type of the column value

String

Example Request:

    • GET http://localhost:7070/db/{graph_name}/label/node/person
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "age":{
            "optional":false,
            "type":"int16"
        },
        "id":{
            "optional":false,
            "type":"int8"
        },
        "name":{
            "optional":false,
            "type":"string"
        }
    }

6.6.4.Schema Import

URI: /db/{graph_name}/schema/text
METHOD: POST
REQUEST:

Field	Description	Type
description	Graph labels description	String

The detail description can refer to TuGraph Manual.

RESPONSE:

Schema import will check the new schema and original schema in database if compatible or not. If yes, this request will add the label only in new schema. If no, will return an error code.

Example request.

    • POST http://localhost:7070/db/graph1/schema/text
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "description": "{\\"schema\\":[{\\"label\\":\\"actor\\",\\"primary\\":\\"aid\\",\\"properties\\":[{\\"name\\":\\"aid\\",\\"type\\":\\"STRING\\"}],\\"type\\":\\"VERTEX\\"}]}"
    }

The value of the above description is the following json serialized string :

{
  "schema": [
    {
      "label": "actor",
      "type": "VERTEX",
      "properties": [{ "name": "aid", "type": "STRING" }],
      "primary": "aid"
    }
  ]
}

Example response.

    • 200: OK
    Output:
    {
        "log": ""
    }

6.7.Vertex Operation

URI format is:

    http://{host}:{port}/db/{graph_name}/node/{vid}

in which vid is a unique integer identifying the vertex, which can be obtained when creating new vertexes or by looking up index.

6.7.1.List Vertex and Label Number

URI: /db/{graph_name}/node
METHOD: GET
RESPONSE:

Field	Description	Type
num_label	the number of vertex label	Integer
num_vertex	the number of vertex	Integer

Note: num_vertex returns an estimate of the number of vertexes, not the exact number. To get the exact number, please use Cypher queries.

6.7.2.Create New Vertex

Insert a vertex into the database.

URI: /db/{graph_name}/node
METHOD: POST
REQUEST:

Field	Description	Type
label	the name of label	String
property	the properties of the vertex	Dictionary

in which property is a dictionary of {column_name:column_value}.

RESPONSE: if successful, return status code 200 and the new vertex’s vid, which can be used in later vertex operations.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/node
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "label" : "Person",
        "property" : {
            "name" : "Passerby A",
            "birthyear" : 1989
        }
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        21
    }

6.7.3.Batch Create Vertexes

TuGraph allows multiple vertices to be inserted as one batch to reduce network overhead.

URI: /db/{graph_name}/node
METHOD: POST
REQUEST:

Field	Description	Type
label	the name of Label	String
fields	the column names	List
values	the values of each vertex	List

in which fields is a list of strings specifying column names, and values is a list in which each element is a list of column_values corresponding to the column names as specified in fields.

RESPONSE: if successful, return status code 200, and return the vid list of newly added vertices in the JSON content, where each vid corresponds to each vertex in the request.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/node
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
        "label" : "Person",
        "fields" : ["name", "birthyear"],
        "values" : [["alex", 2000],
                    ["bob", 1999]]
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            22,
            23
        ]
    }

6.7.4.Get Vertex

URI: /db/{graph_name}/node/{vertex_id}
METHOD: GET
RESPONSE:

Field	Description	Type
label	the name of Label	String
property	property	Dictionary, in the format of {column_name_1:column_value_1, …}

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/5
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "property": {
            "birthyear": 1963,
            "name": "Natasha Richardson"
        },
        "label": "Person"
    }

6.7.5.Delete Vertex

URI: /db/{graph_name}/node/{vertex_id}
METHOD: DELETE
RESPONSE: if successful, return status code 200, and also the following content in JSON:

Field	Description	Type
in	number of incoming edges of the deleted vertex	Integer
out	number of outgoing edges of the deleted vertex	Integer

Example Request:

    • DELETE http://localhost:7070/db/{graph_name}/node/4
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "in": 0,
        "out": 0
    }

6.7.6.Get Vertex Property

URI: /db/{graph_name}/node/{vertex_id}/property
METHOD: GET
RESPONSE: Vertex properties as a dictionary of {column_name:column_value}

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/5/property
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "birthyear": 1963,
        "name": "Natasha Richardson"
    }

6.7.7.Get Vertex Field

URI: /db/{graph_name}/node/{vertex_id}/property/{field}
METHOD: GET
RESPONSE: Value corresponding to the specified field.

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/5/property/name
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "Natasha Richardson"
    }

6.7.8.Update Vertex Property

URI: /db/{graph_name}/node/{vertex_id}
METHOD: PUT
REQUEST:

Field	Description	Type
property	properties to update	Dictionary

RESPONSE: if successful, return status code 200.

Example Request:

    • PUT http://localhost:7070/db/{graph_name}/node/5
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "property" : {
        "birthyear" : 1964,
        "mobile" : "13737299333"
      }
    }

Example Response:

    • 200: OK

6.8.Edge Operation

URI format is:

    http://{host}:{port}/db/{graph_name}/relationship/{euid}

in which euid is a string uniquely identifying the edge, which can be obtained when creating edges or by iterating through the edges of a vertex.

6.8.1.Create Edge

URI: /db/{graph_name}/node/{src_vid}/relationship
METHOD: POST
REQUEST:

Field	Description	Type
label	the label of edge	String
destination	the `vid` of destination vertex	Integer
property	the property of edge	Dictionary

RESPONSE: if successful, return status code 200 and the euid of new created edge (type is String).

Example Request:

    • POST http://localhost:7070/db/{graph_name}/node/{src}/relationship
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "destination" : 14,
      "label" : "BORN_IN",
      "property" : {}
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "1_14_1_0"
    }

6.8.2.Batch Create Edges

URI: /db/{graph_name}/relationship
METHOD: POST
REQUEST:

Field	Description	Type
label	the label of edge	String
fields	the data column name	List
edge	the data of edge	List

where the edge is a list of data, each of which specifies and edge, defined as follows:

Field	Description	Type
source	source vertex id	Integer
destination	destination vertex id	Integer
values	the data list	List

in which values is a list of column values, each of which correspond to the a column name specified in fields.

RESPONSE: if successful, return status code 200 and the list of euids of the newly created edges.

Example Request:

    • POST http://localhost:7070/db/{graph_name}/relationship
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "label" : "knows",
      "fields" : ["from_year", "weight"],
      "edge" : [
          {"source":0, "destination":1, "values":[2011, 0.8]},
          {"source":1, "destination":2, "values":[2008, 0.9]}
      ]
    }

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            "0_1_0_0",
            "1_2_0_0"
        ]
    }

6.8.3.List Out-going Edges

URI: /db/{graph_name}/node/{src}/relationship/out
METHOD: GET
RESPONSE: The list of euids of source vertex’s out-going edges.

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/4/relationship/out
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            "4_5_0_0",
            "4_7_1_2"
        ]
    }

6.8.4.List Incoming Edges

URI: /db/{graph_name}/node/{dst}/relationship/in
METHOD: GET
RESPONSE: The list of euids of destination vertex’s incoming edges.

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/4/relationship/in
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            "0_4_0_0",
            "3_4_3_1"
        ]
    }

6.8.5.List All Edges

URI: /db/{graph_name}/node/{src}/relationship/all
METHOD: GET
RESPONSE:

Field	Description	Type
in	list of incoming edges’ `euid`s	List
out	list of outgoing edges’ `euid`s	List

Example Request:

    • GET http://localhost:7070/db/{graph_name}/node/4/relationship/all
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "out": [
            "4_5_0_0",
            "4_7_1_2"
        ],
        "in": [
            "0_4_0_0",
            "3_4_3_1"
        ]
    }

6.8.6.Get Edge Information

URI: /db/{graph_name}/relationship/{euid}
METHOD: GET
RESPONSE:

Field	Description	Type
label	the label of the edge	String
property	the properties of the edge	Dictionary

Example Request:

    • GET http://localhost:7070/db/graph1/relationship/0_4_0_0
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "property": {
        },
        "label": "MARRIED"
    }

6.8.7.Delete Edge

URI: /db/{graph_name}/relationship/{euid}
METHOD: DELETE
RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1/relationship/14_0_1_0
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.8.8.Get Edge Properties

URI: /db/{graph_name}/relationship/{euid}/property
METHOD: GET
RESPONSE: The dictionary of edge’s properties.

Example Request:

    • GET http://localhost:7070/db/graph1/relationship/14_0_2_0/property
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        {
            "weight": 0.8,
            "begin": 20180922
        }
    }

6.8.9.Get Edge Field

URI: /db/{graph_name}/relationship/{euid}/property/{field}
METHOD: GET
RESPONSE: if successful, return status code 200 and the value corresponding to given field.

Example Request:

    • GET http://localhost:7070/db/graph1/relationship/17_0_2_2/property/charactername
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        "Henri Ducard"
    }

6.8.10.Update Edge Property

URI: /db/{graph_name}/relationship/{euid}
METHOD: PUT
REQUEST:

Field	Description	Type
property	properties to be updated	Dictionary

RESPONSE: if successful, return status code 200.

Example Request:

    • PUT http://localhost:7070/db/graph1/relationship/17_0_2_2
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "property" : {
        "charactername" : "Henri Ducard/passer a"
      }
    }

Example Response:

    • 200: OK

6.9.Index

URI format is:

    http://{host}:{port}/db/{graph_name}/index/{label}/{field}

6.9.1.Create Index

Create an index on a (label, field) pair. Blocks until the index is successfully built.

URI: /db/{graph_name}/index
METHOD: POST
REQUEST:

Field	Description	Type
label	the name of label	String
field	field to be indexed	String
type	the type of index, 0 means nonunique index, 1 means unique index, 2 means pair_unique index	int

RESPONSE: if successful, return status code 200.

Example Request:

    • POST http://localhost:7070/db/graph1/index
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json
    Input:
    {
      "label": "Person",
      "field": "birthyear",
      "is_unique" : false
    }

Example Response:

    • 200: OK

6.9.2.List All Indexes

URI: /db/{graph_name}/index
METHOD: GET
RESPONSE: A list of index specifications, each of which has the same format as use in Create Index.

Example Request:

    • GET http://localhost:7070/db/graph1/index
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            {
                "field": "name",
                "label": "City",
                "is_unique": false
            },
            {
                "field": "title",
                "label": "Film",
                "is_unique": false
            },
            {
                "field": "name",
                "label": "Person",
                "is_unique": true
            },
            {
                "label": "Person",
                "field": "age",
                "is_unique": false
            }
        ]
    }

6.9.4.Delete Index

URI: /db/{graph_name}/index/{label}/{field}
METHOD: DELETE
RESPONSE: if successful, return status code 200.

Example Request:

    • DELETE http://localhost:7070/db/graph1/index/Person/name
    • Accept: application/json; charset=UTF-8

Example Response:

    • 200: OK

6.9.5.Get Vertex by Index

URI: /db/{graph_name}/index/{label}/?field={field}&value={value}
METHOD: GET
RESPONSE: A list of vids.

Example Request:

    • GET http://localhost:7070/db/graph1/index/Person/?field=birthyear&value=1986
    • Accept: application/json; charset=UTF-8

Example Response:

6.10.Data Import

URI: /db/{graph_name}/import/text
METHOD: POST
REQUEST:

Field	Description	Type
description	description of the file content	String
data	contents of the file to be imported (recommended to have a size of 16MB, has a hard limit of 17MB)	Strings / Arrays / Objects
continue_on_error	whether to continue import when an error occurred (optional, default is `false`)	Bool
delimiter	delimiter used in the data file (optional, default is `“,”`)	String

The details of the description field can be found in TuGraph Import Tool.

delimiter can be a single character or multi-character string, but must not contain \r or \n.

data can be one of the following:

String, such as "1,2\n3,4\n"
Array of ASCII codes, such as [49,44,50,10,51,44,52,10]
Dictionary shaped like the above array, such as {"0":49,"1":44,"2":50,"3":10,"4":51,"5":44,"6":52,"7":10}

RESPONSE:

The system will not automatically perform actions such as creating a new label, adding an index, and so on. Before you do this, please make sure that the label involved already exists and has an appropriate index.

If the import is successful, return code 200 and return log information (possibly empty) in the log field. Otherwise, returns status code 400. None of the data is imported on failure, and error message is set in error_message.

Example Request:

    • POST http://localhost:7070/db/graph1/import/text
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "description": "{\\"files\\":[{\\"columns\\":[\\"SRC_ID\\",\\"role\\",\\"DST_ID\\"],\\"format\\":\\"CSV\\",\\"label\\":\\"role\\",\\"SRC_ID\\":\\"actor\\",\\"DST_ID\\":\\"movie\\"}]}"}",
      "data": "1,Role1,2\n3,Role2,4\n",
      "continue_on_error": true
    }

The value of the above description is the following json serialized string :

{
  "files": [
    {
      "format": "CSV",
      "label": "role",
      "SRC_ID": "actor",
      "DST_ID": "movie",
      "columns": ["SRC_ID", "role", "DST_ID"]
    }
  ]
}

Example Response:

    • 200: OK
    Output:
    {
        "log": "Missing src uid 1\n"
    }

Because the request specifies continue_on_error: true, the returned log indicates that the first edge cannot be inserted because there is no vertex with uid==1, while the second edge was imported successfully.

6.11.Miscellany

URI format is:

    http://{host}:{port}/db/{graph_name}/misc

6.11.1.Extract Subgraph

Give a set of vids and return the minimum subgraph which contains the vertex set and the edges between them.

URI: /db/{graph_name}/misc/sub_graph
METHOD: POST
REQUEST:

Field	Description	Type
vertex_ids	vertex id set	List

RESPONSE:

Field	description	Type
nodes	vertex information	List, each element contains vid, label, and properties.
relationships	edge information	List, each element contains src, dst, euid, label, and properties.

Example Request:

    • POST http://localhost:7070/db/graph1/misc/sub_graph
    • Accept: application/json; charset=UTF-8
    • Content-Type: application/json; charset=UTF-8
    Input:
    {
      "vertex_ids": [2, 5, 14, 20]
    }

Example Response:

    • 200: OK
    Output:
    {
        "nodes": [
            {
                "label": "Person",
                "properties": {
                    "birthyear": 1937,
                    "name": "Vanessa Redgrave"
                },
                "vid": 2
            },
            {
                "label": "Person",
                "properties": {
                    "birthyear": 1963,
                    "name": "Natasha Richardson"
                },
                "vid": 5
            },
            {
                "label": "City",
                "properties": {
                    "name": "London"
                },
                "vid": 14
            },
            {
                "label": "Film",
                "properties": {
                    "title": "Camelot"
                },
                "vid": 20
            }
        ],
        "relationships": [
            {
                "destination": 5,
                "label": "HAS_CHILD",
                "properties": {
                    "birthyear": 1937,
                    "name": "Vanessa Redgrave"
                },
                "source": 2
            },
            {
                "destination": 14,
                "label": "BORN_IN",
                "properties": {
                    "birthyear": 1937,
                    "name": "Vanessa Redgrave"
                },
                "source": 2
            },
            {
                "destination": 20,
                "label": "ACTED_IN",
                "properties": {
                    "birthyear": 1937,
                    "charactername": "Guenevere",
                    "name": "Vanessa Redgrave"
                },
                "source": 2
            },
            {
                "destination": 14,
                "label": "BORN_IN",
                "properties": {
                    "birthyear": 1963,
                    "name": "Natasha Richardson"
                },
                "source": 5
            }
        ]
    }