Introduction

TigerGraph's REST API endpoints exist on the REST++ and the GSQL server. REST++ (or RESTPP) is the TigerGraph customized REST server. Our API accepts URL-encoded query string parameters, JSON-encoded request bodies and returns JSON encoded responses. This user guide provides information on how to engage with our REST APIs: the introduction section explains how to send requests, pass parameters, and format request bodies, while the subsequent sections describe in detail each endpoint and its input and output. 
To submit a request, send an HTTP request to the REST++ server or the GSQL server. By default, the REST++ server listens for requests at port 9000 and the GSQL server listens on port 14240. A request needs to specify five things:
The request method (GET, POST, PUT, or DELETE)
The endpoint address
Any required or optional request parameters in URL encoding
For POST requests, a data payload (i.e., request body) in JSON encoding unless otherwise specified
In some cases, request header parameters
For requests that are sent to the GSQL server, the sender needs to provide TigerGraph user credentials for the request to be accepted. If authentication is enabled on the RESTPP server, a request token needs to be included in the request header as well. 
In a test or development environment, the requester may be on the same server as REST++. In this case, the server IP is localhost.
Query String Parameters
TigerGraph's API endpoints accept parameters in URL encoding, which is straightforward in the case of string, number, and boolean values. However, some parameters are more complex and require specific formatting. The list below describes how to format the complex type parameter values when executing a query.
Parameter type
Description
Example
SET or BAG of primitives
Assign multiple values to the same parameter name.
​
A SET<INT> parameter named p1 is assigned 3 integers:
p1=1&p1=5&p1=10
VERTEX with a defined type
Use the primary key of the vertex.
​
A VERTEX<person> parameter namedvp is assigned a vertex whose ID is "person2":
vp=person2
VERTEX without a defined type
Use <parameter_name>.<parameter_type> to specify the type of the parameter, and also provide the primary key of the vertex.
​
A VERTEX parameter named va is assigned a person type vertex whose ID is"person1" 
va=person1&va.type=person
SET or BAG of vertices with a defined type
Same as a SET or BAG of primitives, where the value for each element is the primary key of the vertex.
A SET<VERTEX<person>> parameter named vp is assigned two vertices with IDs person3 and person4: 
vp=person3&vp=person4
SET or BAG of vertices without a defined type
The SET or BAG must be treated as an array, specifying the order of the elements with indices [0], [1], etc.
A SET<VERTEX> parameter named vpis assigned a person type vertex with an ID of person1 and a post type vertex with an ID of 11 :
vp[0]=person1&vp[0].type=person&vp[1]=11&vp[1].type=post
Input Data for POST requests
Input data for POST requests should be in JSON format, unless the endpoint specifically accepts data in other formats. There are two ways to supply the data: inline or in a separate file.
Inline Data
The data should be formatted as a single string without linebreaks. If using curl, use the -d option, followed by the JSON string.
Syntax for a POST request with Inline Data Payload
curl -X POST -d 'json_string' "http://server_ip:9000/path_to_endpoint?request_parameters"
The following example uses the POST /graph endpoint to insert one User type vertex whose ID is "id6" into the graph called "socialNet".
Example using inline input data
curl -X POST -d '{"vertices":{"User":{"id6":{"id":{"value":"id6"}}}}}' "http://localhost:9000/graph/socialNet"
Data File
Often it will be more convenient for the input data to be in a separate file, especially if the data is large.
For curl, use --data-binary <path_to_file> as in the example below:
Syntax for a POST request with Payload Data File
curl -X POST --data-binary <path_to_file> "http://server_ip:9000/path_to_endpoint?parameter1=<parameter1>"
Formatting Data in JSON
Data of primitive types, including INT, UINT, FLOAT, DOUBLE, STRING, BOOL, and DATETIME, as well as arrays and objects, follow the standard JSON Data Interchange Syntax. This subsection describes how to format complex data types.
Data type
Description
Example
SET or BAG of primitives
Use a JSON array.
A set of primitive values:
[0.5, 0,6, 0.7]
VERTEX
Use a JSON object that has an"id" field whose value is the primary key of the vertex
and a"type"field whose value is the type of the vertex.
A person vertex with an ID of "Tom": 
{"id": "Tom", "type": "person"}
Vertices with Composite Keys
If a vertex has a composite key composed of N attributes, then N values must be provided for the "id" . The values can be presented either as a JSON object with N key-value pairs, or as a JSON array with a list of N values in the same order as defined in the schema.
The example below shows the two methods for a  vertex v having a composite primary key composed of the three attributes id, name, and label.
Option1
Option2
Option1
Vertex v with composite key as JSON object
{
  "v": {
    "id": {
      "id": 3,
      "name": "c",
      "label": 300
    },
    "type": "v3"
  }
}
Option2
Vertex v with composite key as JSON array
{
  "v": {
    "id": {
      "id": [3, "c", 300] // The values in the array must be in the same
                          // order as they are defined in the schema
    },
    "type": "v3"
  }
}
SET or BAG of Vertices
 To describe a SET or BAG of vertices in JSON, use a JSON array with vertex objects nested in the SET or BAG array.
Output Responses
All TigerGraph REST responses are in JSON format. The output JSON object has four fields: "version", "error", "message", and "result". 
"version" - this field describes the version of the running TigerGraph instance. 
"error" - a boolean value to indicate if there is an error in processing the request. If there is an error, the "error" field will be true.
"message" - the error message when there is an error. It will be an empty string in the case of a successful request.
"result" - this field contains the resulting data from the request. Details about the result of each built-in endpoint are described in the Built-in Endpoints section.
To make the JSON output more human-readable, use the jq command or Python json library built into most Linux installations:
curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | jq .
curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | python -m json.tool
Authentication
REST++ Server Requests
By default, TigerGraph REST++ endpoints are public: anyone with access to the HTTP ports of the TigerGraph server can run your endpoints. When REST++ authentication is enabled, then a valid authorization token must be included in the header.
The REST++ server implements OAuth 2.0-style authorization as follows: Each user can create one or more secrets (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 tokens (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.
Using Tokens
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:
curl GSQL request, with authorization token in header
curl -X GET -H "Authorization: Bearer <token>" '<request_URL>'
Here is a sample request: 
curl -X GET -H "Authorization: Bearer 01234567abcdefgh01234567abcdefgh" "http://localhost:9000/graph/socialNet/vertices/User?limit=3"
GSQL Server Requests
All requests made to the GSQL Server must be accompanied by your user credentials. You can use the curl -u option to pass in the username and password of the TigerGraph user:
curl -X GET -u <username>:<password> "http://localhost:14240/<path_to_endpoint>
To keep your credentials more secure, one way to avoid having the user name and password on the command line is to instead use a .netrc file or a config file. If you are in interactive mode, you can also use the -u option without specifying the password, and then curl will prompt for the password.
Size and Time limits
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.
Request Body Size
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 200 (in MB). To increase this limit, use the following gadmin command:
gadmin config set Nginx.ClientMaxBodySize NNN
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.
GSQL Query Timeout
By default, an HTTP request in the TigerGraph system times out after 16 seconds.  to customize this timeout limit for a particular query instance, you can set the GSQL-TIMEOUT parameter in the request header. If you are using curl to submit your RESTPP request, the syntax would be the following:
curl -X <GET/POST> -H "GSQL-TIMEOUT: <timeout value in ms>" '<request_URL>'
Response Size
You can specify the response size limit of an HTTP request with the following header:
curl -X <GET/POST> -H "RESPONSE-LIMIT: <size limit in byte>" '<request_URL>'
If the response size is larger than the given limit, an error message will be returned instead of the actual query result:
{
  "error": true,
  "message": "The query response size is 256MB, which exceeds limit 32MB.",
  "results": [],
  "code": "REST-4000"
}

Developer's Guides - Previous

RESTful API User Guide

Built-in Endpoints

Last updated 2 months ago

Parameter type	Description	Example
`SET` or `BAG` of primitives	Assign multiple values to the same parameter name.	A `SET<INT>` parameter named `p1` is assigned 3 integers: `p1=1&p1=5&p1=10`
`VERTEX` with a defined type	Use the primary key of the vertex.	A `VERTEX<person>` parameter named`vp` is assigned a vertex whose ID is `"person2"`: `vp=person2`
`VERTEX` without a defined type	Use `<parameter_name>.<parameter_type>` to specify the type of the parameter, and also provide the primary key of the vertex.	A `VERTEX` parameter named `va` is assigned a `person` type vertex whose ID is`"person1"` `va=person1&va.type=person`
`SET` or `BAG` of vertices with a defined type	Same as a `SET` or `BAG` of primitives, where the value for each element is the primary key of the vertex.	A `SET<VERTEX<person>>` parameter named `vp` is assigned two vertices with IDs `person3` and `person4`: `vp=person3&vp=person4`
`SET` or `BAG` of vertices without a defined type	The `SET` or `BAG` must be treated as an array, specifying the order of the elements with indices `[0]`, `[1]`, etc.	A `SET<VERTEX>` parameter named `vp`is assigned a `person` type vertex with an ID of `person1` and a `post` type vertex with an ID of `11` : `vp[0]=person1&vp[0].type=person&vp[1]=11&vp[1].type=post`

Introduction

Query String Parameters

Input Data for `POST` requests

Inline Data

Data File

Formatting Data in JSON

Vertices with Composite Keys

`SET` or `BAG` of Vertices

Output Responses

Authentication

REST++ Server Requests

Using Tokens

GSQL Server Requests

Size and Time limits

Request Body Size

GSQL Query Timeout

Response Size