# 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](#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](#CPU-Status)                                     |
| disk           | disk IO information            | Dictionary, format refers [Disk Status](#Disk-Status)                                   |
| memory         | memory information             | Dictionary, format refers [Memory Status](#Memory-Status)                               |
| db_space       | graph database storage         | Dictionary, format refers [Graph Database Storage](#Graph-Database-Storage)             |
| db_config      | graph database configuration   | Dictionary, format refers [Graph Database Configuration](#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 :

```json
{
  "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 `euid`s 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 `euid`s 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 `euid`s 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](#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.3.List Indexes Related with Specified Label

- **URI**: `/db/{graph_name}/index/{label}`

- **METHOD**: GET

- **RESPONSE**: A list of index specifications, each of which has the same format as use in [Create Index](#Create-Index).

**Example Request:**

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

**Example Response:**

```
    • 200: OK
    • Content-Type: application/json; charset=UTF-8
    Output:
    {
        [
            {
                "label": "Person",
                "field": "name",
                "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 `vid`s.

**Example Request:**

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

**Example Response:**

```
    • 200: OK
    Output:
    {
        [
            1,
            8
        ]
    }
```





### 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](../6.utility-tools/1.data-import.md).

`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 :

```json
{
  "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 `vid`s 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
            }
        ]
    }
```