# TuGraph RESTful API

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

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

This document specifiers the TuGraph HTTP RESTful API.

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

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

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

### 2.2. Request Type

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

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

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

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

| body parameter            | parameter description         | parameter type |
|------------------|------------------|----------------|
| jwt              | token               | string         |
| is_admin         | Whether the user is an admin     | bool           |
| default_password | Whether it is the default password           | bool           |

**Example request.**

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

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

- **URI**:     /logout
- **METHOD**:  POST
- **REQUEST**:
  The http request header carries the token returned by login interface. The specific string to be filled is `Bearer ${jwt}`, where `${jwt}` is the "jwt" returned from the login interface，and the body has no parameters

| header parameter           | parameter description | parameter type   |
|------------------|-----------------------|------------|
| Authorization              | Bearer ${jwt}         | string |

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

| body parameter         | parameter description           | parameter type |
|------------------|--------------------|----------------|
| is_admin         | Whether the user is an admin    | bool           |

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

- **URI**:     /refresh
- **METHOD**:  POST
- **REQUEST**:
  The http request header carries the token returned by login interface. The specific string to be filled is `Bearer ${jwt}`, where `${jwt}` is the "jwt" returned from the login interface，and the body has no parameters

| header parameter           | parameter description | parameter type   |
|------------------|-----------------------|------------|
| Authorization              | Bearer ${jwt}         | string |

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

| body parameter | parameter description | parameter type |
|----------------|------|----------------|
| jwt            | token  | string         |
| is_admin       | Whether the user is an admin    | bool           |

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

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

| header parameter           | parameter description | parameter type   |
|------------------|-----------------------|------------|
| Authorization              | Bearer ${jwt}         | string |

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

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

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

**Example request.**

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