Source: https://dev-docs.nebula-graph.io/v5.3.2/apis/
Documentation version: v5.3.2

# REST API

Caution

The REST API is a preview feature provided for evaluation and testing purposes only. It is not recommended for production use.

Developers can access NebulaGraph Database Developer Edition through its REST API over HTTP. The REST API is designed to be simple and intuitive, enabling various operations such as creating graphs, managing nodes and edges, executing queries, and retrieving system metrics.

For a complete workflow from configuring NebulaGraph Database Developer Edition access to returning application JSON, see [Build a service with the REST API](https://dev-docs.nebula-graph.io/v5.3.2/app-development/rest-api/).

## Endpoint URL

The endpoint URL is structured as follows: `{protocol}://{host}:{port}/{endpoint}`, where:

- `{protocol}`: The communication protocol. Valid values are `http` or `https`. Default is `http`.
- `{host}`: The hostname or IP address of the development machine running the Graph service. Use `127.0.0.1` when the client and Docker run on the same machine, or the development machine's IP address from another computer. For deployment instructions, see [Quick start](https://dev-docs.nebula-graph.io/v5.3.2/get-started/deploy/).
- `{port}`: The port that the Graph service is running on under the specified protocol. Default is `19669`.
- `{endpoint}`: The specific API endpoint you want to access. For example, `/gql`. For more information, see [Endpoints](https://dev-docs.nebula-graph.io/v5.3.2/apis/#endpoints).

## Authentication

The REST API uses JWT (JSON Web Token) bearer authentication for securing endpoints. You must obtain a JWT token through the endpoint `/auth` and include the token in the `Authorization` header for subsequent requests.

For example, to request a JWT token, send a POST request to the endpoint `/auth` as follows:

````
curl -X POST \
  http://localhost:19669/auth \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "your_username", 
  "password": "your_password" 
}'

````

Replace `your_username` and `your_password` with your actual username and password that are required to access the Graph service.

If the authentication is successful, a response containing the JWT token as follows is returned:

````
{
  "code": "00000",
  "message": "",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

````

Save the value of `data.token` from the authentication response. For requests to protected endpoints, include the token in the `Authorization` header using the `Bearer` authentication scheme. For example:

````
TOKEN='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

curl -X POST \
  http://localhost:19669/gql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "gql": "SHOW GRAPHS"
}'

````

The `/auth`, `/api-docs`, `/health`, `/info`, and `/metrics` endpoints do not require authentication. Other endpoints require a valid JWT token.

## Request structure

Each request to the REST API must be structured as an HTTP request with the following components:

- Method: The HTTP method used for the request, such as GET, POST, PATCH, or DELETE.
- Headers: HTTP headers that may include `Content-Type`, `Authorization`, and other custom headers as needed.
- Endpoint URL: The full URL of the endpoint as described in [Endpoint URL](https://dev-docs.nebula-graph.io/v5.3.2/apis/#endpoint_url).
- Path parameters: Parameters included in the URL path, such as `/graphs/{graphName}`. 
- Query parameters: Optional parameters appended to the URL for filtering or modifying the request. For example, `?edgeType=FOLLOWS&srcId=1&dstId=2`.
- Request body: The payload sent with the request in JSON format. Required for POST and PATCH requests.

## Response structure

Each API response typically includes an HTTP status code, response headers, and a response body in JSON format. The response body usually contains the following fields:

- `code`: Status code of the operation. When investigating a failed request, record the HTTP status, `code`, and `message` together.
- `message`: Description or result of the operation.
- `data`: Actual data returned from the operation, if applicable.
- `summary`: Summary of the operation, such as the numbers of nodes and edges affected, if applicable.

## Endpoints

This section lists the available endpoints in the REST API and their functionalities.

 | Endpoint | HTTP Method | Description
 | `/auth` | POST | Authenticate users and retrieve JWT tokens.
 | `/signout` | POST | Sign out users and invalidate JWT tokens.
 | `/api-docs` | GET | Retrieve the interactive API reference documentation.
 | `/health` | GET | Retrieve the health status of the Graph service.
 | `/info` | GET | Retrieve general information about NebulaGraph Database Developer Edition, such as version and build details.
 | `/metrics` | GET | Retrieve system metrics.
 | `/graphtypes` | GET | Retrieve all graph types.
 |  | POST | Create a graph type.
 | `/graphtypes/{name}` | GET | Retrieve a graph type.
 |  | PATCH | Alter a graph type.
 |  | DELETE | Delete a graph type.
 | `/graphs` | GET | Retrieve all graphs.
 |  | POST | Create a graph.
 | `/graphs/{name}` | GET | Retrieve a graph by name.
 |  | PATCH | Rename a graph.
 |  | DELETE | Delete a graph.
 | `/graphs/{graphName}/nodes` | GET | Retrieve all nodes in a graph or specific nodes by individual properties.
 |  | POST | Insert nodes to a graph.
 | `/graphs/{graphName}/nodes/{id}` | GET | Retrieve a node by ID.
 |  | PATCH | Update a node by ID.
 |  | DELETE | Delete a node by ID.
 | `/graphs/{graphName}/edges` | GET | Retrieve all edges in a graph.
 |  | PATCH | Update edges by the IDs or primary keys of the source and destination nodes.
 |  | POST | Insert edges to a graph by the IDs or primary keys of the source and destination nodes.
 |  | DELETE | Delete edges by source and destination node IDs.
 | `/procedures` | GET | Retrieve all procedures.
 | `/procedures/{name}` | GET | Retrieve a procedure by name.
 |  | DELETE | Delete a procedure by name.
 | `/procedures/{name}/call` | POST | Call a procedure by name.
 | `/gql` | POST | Execute a GQL query.
 | `/sessions/{sessionId}/query` | DELETE | Kill the query in the session specified by `sessionId`.

Note

For detailed information about each endpoint, including request and response parameters, visit the API reference documentation via the endpoint `/api-docs`.

## Examples

The following examples demonstrate how to use the REST API to perform common operations.

### Create a graph type

````
curl -X POST \
  http://localhost:19669/graphtypes \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "name": "test_graph_type",
  "ifNotExists": true,
  "nodeTypes": [
    {
      "name": "Person",
      "labels": [
        "Person"
      ],
      "props": [
        {
          "name": "id",
          "type": "int",
          "primaryKey": true
        },
        {
          "name": "name",
          "type": "string",
          "notNull": false
        },
        {
          "name": "age",
          "type": "int",
          "nullable": true
        }
      ]
    },
    {
      "name": "City",
      "labels": [
        "City"
      ],
      "props": [
        {
          "name": "zipcode",
          "type": "string",
          "notNull": false
        },
        {
          "name": "name",
          "type": "string",
          "notNull": false
        }
      ],
      "primaryKey": [
        "zipcode",
        "name"
      ]
    }
  ],
  "edgeTypes": [
    {
      "name": "LIVES_IN",
      "direction": "PointingLeft",
      "srcNodeType": "Person",
      "dstNodeType": "City",
      "labels": [
        "LIVES"
      ],
      "props": [
        {
          "name": "start_time",
          "type": "datetime",
          "notNull": true
        }
      ],
      "multiEdgeKey": [
        "start_time"
      ]
    }
  ]
}'

````

### Create a graph

````
curl -X POST \
  http://localhost:19669/graphs \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "name": "test_graph",
  "graphType": "test_graph_type",
  "ifNotExists": true
}'

````

### Insert nodes to the graph

````
curl -X POST \
  http://localhost:19669/graphs/test_graph/nodes \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
  "nodeType": "Person",
  "onConflict": "replace",
  "nodes": [
    {"id": 1, "name": "p1"},
    {"id": 2, "name": "p2"}
  ]
}'

````

### Query nodes in the graph

````
curl -X POST \
  http://localhost:19669/gql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{ "gql": "USE test_graph MATCH (v:Person) RETURN v LIMIT 10" }'

````

## More information

[GQL guide](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/)