PLEASE FIND THE MOST UPDATED CONTENT FOR THIS ARTICLE ON OUR DOCUMENTATION SITE:
Version 1.2 to 2.1
Copyright © 2015-2018 TigerGraph. All Rights Reserved.
For technical support on this topic, contact
with a subject line starting with “REST++”
Introduction – What is REST++?
system uses the well-known REpresentational State Transfer (REST) architecture to manage communication with the TigerGraph core components, the Graph Processing Engine (GPE) and Graph Storage Engine (GSE). REST++ (or RESTPP) is the TigerGraph customized REST server. (See Figure 1 below) When an upper layer component, such as the Platform Web UI or GSQL, wishes to access the graph engine, it sends a request to the REST++ server. Users can also communicate directly with the REST++ server, either by using one of the standard REST APIs included with the system, or by authoring and then employing a custom endpoint API. This document describes the APIs for the built-in endpoints, which provides methods for basic querying and manipulation of the graph data.
: TigerGraph System Block Diagram
Like most RESTful systems, REST++ employs the HTTP protocol (specifically HTTP/1.1 without request pipelining). Accordingly, REST APIs feature request methods and URLs, response status codes, and data responses. This guide describes the request methods and URLs used to query, update, and delete from the graph data. It also describes the format of the data responses.
The TigerGraph REST APIs employ three HTTP request methods:
is used to request data.
is used to send data.
is used to delete data.
If the user submits an unsupported HTTP method, the API will return an error message: “endpoint not found”.
Submitting a REST++ Request
To submit a request, an HTTP request is sent to the REST++ server. By default, the REST++ server listens for requests at port 9000. A request needs to specify three things:
- the request method (GET, POST, or DELETE),
- the endpoint address, and
- any required or optionally request parameters.
The endpoint address is the the form of a HTTP URL.
Request parameters are appended to the end using standard HTTP query string format.
In a test or development environment, the requester may be on the same server as REST++. In this case, the server_ip is
The Linux curl command is the most convenient way to submit the HTTP request to the REST++ server.
Assume the REST++ server is on the local machine (typical configuration) and there is a graph called socialNet. To get all the User vertices from socialNet:
To list only the first three vertices, we can set limit = 3:
The HTTP request methods GET, POST, and DELETE are case sensitive. Also, curl option flags are case sensitive.
Input Data for POST
Input data for POST requests should be in JSON format. There are two ways to supply the data: inline or in a separate file.
The data should be formatted as a single string without linebreaks. Use the curl –
option, followed by the JSON string.
The following example uses the POST /graph endpoint to insert one User type vertex whose id value is “id6” into the graph called “socialNet”.
Often it will be more convenient for the input data to be in a separate file, especially if it is large.
Use the curl option
as in the example below:
If we now store the data string in a file (say, my_input.json), then the example above becomes the following:
All TigerGraph REST responses are in JSON format. The format details for each built-in endpoint are described below in the Built-in Endpoints section. By default, the output is designed for machine reading, with no extra spaces or linefeeds. The output JSON object can have three fields: error, message, and result.
This document has been updated to show JSON output API v2. Earlier versions of the TigerGraph platform produced JSON output in a slightly different format (v1). Newer platforms can be configured to produce output in either v2 or v1 formats.
To make the output more human readable, use the
or Python json library built into most Linux installations. Specifically,
In the Collaborative Filter example in the
GSQL Demo Examples v2.1
document, the request
without postprocess formatting returns the following:
On the other hand,
returns this much more readable output:
The TigerGraph system administration can choose to enable user authentication for the REST++ endpoints. If authentication is not enabled, then TigerGraph REST++ endpoints are public; anyone with access to the HTTP ports of the TigerGraph server can run your endpoints. When REST++ authentification is enabled, then a valid authorization token must be included in the header. To see how to enable/disable REST++ authentication, see the document
Managing User Privileges and Authentication v2.1
The REST++ server implements OAuth 2.0-style authorization as follows: Each user can create one or more
(unique pseudorandom strings). Each secret is associated with a particular user and the user’s privileges for a particular graph. Anyone who has this secret can invoke a special REST endpoint to generate authorization
(other pseudorandom strings). An authorization token can then be used to perform TigerGraph database operations via other REST endpoints. Each token will expire after a certain period of time. The TigerGraph default lifetime for a token is 1 month.
Requesting A Token with GET /requesttoken
A user must have a secret before they create a token. Secrets are generated in GSQL (see
Managing User Privileges and Authentication v2.1
). The special endpoint
GET /requesttoken is used to create a token. The endpoint has two parameters:
- secret (required): the user’s secret
- lifetime (optional): the lifetime for the token, in seconds. The default is one month, approximately 2.6 millon seconds.
Once REST++ authentication is enabled, a valid token should always be included in the HTTP header. If you are using curl to format and submit your REST++ requests, then use the following syntax:
For example, if the token = 01234567abcdefgh01234567abcdefgh, then the collaborative filtering example shown above would be
The maximum length for the request URL is 8K bytes, including the query string. Requests with a large parameter size should use a data payload file instead of inline data.
The maximum size for a request body, including the payload file, is set by the system parameter nginx.client_max_body_size. The default value is 128 (in MB). To increase this limit to xxx MB, use the following gadmin command:
The upper limit of this setting is 1024 MB. Raising the size limit for the data payload buffer reduces the memory available for other operations, so be cautious about increasing this limit.
GET /echo and POST /echo
These endpoints are simple diagnostic utilities which respond with the following message.
POST /echo has the same response as GET /echo.
This endpoint returns a list of the installed endpoints and their parameters. There are three types of endpoints, described in the table below.
|builtin||preinstalled in the TigerGraph system|
|dynamic||generated when compiling GSQL queries|
To include one more more of the endpoint types in the output, include
in the parameter query string for each type. For example, “builtin=true&static=true” will include builtin and static endpoints.
If no type parameters are provided, all endpoints are returned.
There are over a dozen built-in endpoints, and some have several parameters, so the formatted JSON output from the
option is over 300 lines long. It is listed in full in Appendix A. To illustrate the format, we show a small excerpt: the output for the
This endpoint returns real-time query performance statistics over the given time period, as specified by the
parameter. The seconds parameter must be a positive integer less than or equal to 60. The REST++ server maintains a truncated log of requests from the current time and backward for a system-configured
. Only those endpoints which have completed or timed out during the requested number of
and are within the
be included in the statistics report. For example:
The statistics data are returned in JSON format. For each endpoint which has statistics data, we return the following items:
- CompletedRequests – the number of completed requests.
- QPS – query per second.
- TimeoutRequests – the number of requests not returning before the system-configured timeout limit. Timeout requests are not included in the calculation of QPS.
- AverageLatency – the average latency of completed requests.
- MaxLatency – the maximum latency of completed requests.
- MinLatency – the minimum latency of completed requests.
- LatencyPercentile – The latency distribution. The number of elements in this array depends on the
parameter of this endpoint. By default, segments is 10, meaning the percentile range 0-100% will be divided into ten equal segments: 0%-10%, 11%-20%, etc.
must be [1, 100].
Note: If there is no query sent in the past given seconds, a empty json will be returned.
This endpoint returns the git versions of all components of the system. This can be useful information when requesting help from TigerGraph’s support team.
Accessing and Modifying the Graph Data
To support multiple graphs within one system, the graph data REST endpoint URLs have been modified to include a graph name.