RESTPP Requests

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:

1. the request method (GET, POST, or DELETE),

2. the endpoint address, and

3. 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 localhost .

The Linux curl command is the most convenient way to submit the HTTP request to the REST++ server.

REST Request Format

curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters"

Example:

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:

Example: Get all User vertices

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User"

To list only the first three vertices, we can set limit = 3:

Example: Get up to 3 User vertices

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User?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.

Inline Data

The data should be formatted as a single string without linebreaks. Use the curl - 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 value 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 it is large.

Use the curl option --data-binary @path_to_file as in the example below:

Syntax for a POST request with Payload Data File

curl -X POST --data-binary @json_file "http://server_ip:9000/path_to_endpoint?request_parameters"

If we now store the data string in a file (say, my_input.json), then the example above becomes the following:

Example using inline input data

curl -X POST --data-binary @my_input.json "http://localhost:9000/graph/socialNet"

REST++ Output

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 jq command or Python json library built into most Linux installations. Specifically,

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

Example:

In the Collaborative Filter example in the GSQL Demo Examples document, the request

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

without postprocess formatting returns the following:

{"version":{"api":"v2","schema":0},"error":false,"message":"","results":[{"v_id":"id2","v_type":"User","attributes":{}},{"v_id":"id5","v_type":"User","attributes":{}},{"v_id":"id3","v_type":"User","attributes":{}}]}

On the other hand,

curl -X GET http://localhost:9000/graph/socialNet/vertices/User?limit=3 | jq .

returns this much more readable output:

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "v_id": "id2",
      "v_type": "User",
      "attributes": {}
    },
    {
      "v_id": "id5",
      "v_type": "User",
      "attributes": {}
    },
    {
      "v_id": "id3",
      "v_type": "User",
      "attributes": {}
    }
  ]
}

REST++ Authentication

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++ authentication 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.

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.

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). 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 million seconds.

Example: REST++ Request to Generate a Token

curl -X GET 'localhost:9000/requesttoken?secret=jiokmfqqfu2f95qs6ug85o89rpkneib3&lifetime=1000000'

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>'

For example, if the token = 01234567abcdefgh01234567abcdefgh, then the collaborative filtering example shown above would be

curl -X GET -H "Authorization: Bearer 01234567abcdefgh01234567abcdefgh" "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

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.

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:

gadmin --set nginx.client_max_body_size xxx -f

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.

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>'