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.
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:
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 - d 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 --data-binary @path_to_file 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.
In the Collaborative Filter example in the GSQL Demo Examples 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++ 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.
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.
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
If the /requesttoken endpoint is used with the PUT command and the request token already exists, the given token will be refreshed.
If the DELETE command is used, the given request token will be deleted.
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.
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:
You can specify the response size limit of a HTTP request with the following header:
If the response size is larger than the given limit, an error message will be returned instead of the actual query result: