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.

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.
• {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.

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.
• 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