REST Endpoints for the Graph Server

19 REST Endpoints for the Graph Server

This chapter describes the graph server REST API endpoints.

The graph server REST API supports two different versions. It is recommended that you use version 2 of the API.

Graph Server REST API Version 2
Learn about the graph server REST API version 2 (v2).
Graph Server REST API Version 1
Learn about the graph server REST API version 1 (v1).

Parent topic: Using the Graph Server (PGX)

19.1 Graph Server REST API Version 2

Learn about the graph server REST API version 2 (v2).

This API version supports a token-based authentication for the REST endpoints. Therefore, you must first obtain an access token which can be used in the subsequent REST API requests.

Parent topic: REST Endpoints for the Graph Server

19.1.1 Get an Authentication Token

POST https://localhost:7007/auth/token

Get an authentication token which can be used to authenticate the REST API requests.

Request

Request Header

Accept: application/json; charset=UTF-8
Content-Type: application/json

Table 19-1 Request Body Parameters

Parameter	Type	Description	Required
`username`	string	Name of the user	Yes
`password`	string	Password for the user	Yes
`createSession`	boolean	To determine if a session needs to be created	Optional. Set it to `true` if you want to run queries against the graph server (PGX).

Sample Request Body

{
    "username": "graphuser",
    "password": "<password_for_graphuser>",
    "createSession": true 
}

Response

201 Created
Content-Type: application/json

Sample Response Body

{
    "access_token": "<token>"
    "token_type": "bearer",
    "expires_in": 3600
}

cURL Example

curl --location 'https://localhost:7007/auth/token' \
--header 'Content-Type: application/json' \
--data '{ 
    "username": "graphuser",
    "password": "<password_for_graphuser>",
    "createSession": true 
}'

Parent topic: Graph Server REST API Version 2

19.1.2 Refresh an Authentication Token

PUT https://localhost:7007/auth/token

Refresh a valid access token.

Request

Request Header

Accept: application/json; charset=UTF-8
Content-Type: application/json

Table 19-2 Request Body Parameters

Parameter	Type	Description	Required
`token`	string	Access token value	Yes
`createSession`	boolean	Flag to determine if a session needs to be created	Optional. Set it to `true` if you want to run queries against the graph server (PGX).

Sample Request Body

{
    "token": "<token>",
    "createSession": true
}

Response

201 Created
Content-Type: application/json

Sample Response Body

{
    "access_token": "<token>"
    "token_type": "bearer",
    "expires_in": 3600
}

cURL Example

curl --location --request PUT 'https://localhost:7007/auth/token' \
--header 'Content-Type: application/json' \
--data '{
    "token": "<token_value>",
    "createSession": true
}'

Parent topic: Graph Server REST API Version 2

19.1.3 Get Graphs

GET https://localhost:7007/v2/graphs

Get the list of graphs for the specified driver.

Version: v2

Request

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Request Query Parameter

driver (required): Specifies the PGQL driver value. This is a mandatory parameter. Supported values are as follows:
- GRAPH_SERVER_PGX: Graphs loaded into the graph server (PGX)
- PGQL_IN_DATABASE: PGQL property graphs in the database
- SQL_IN_DATABASE: SQL property graphs in the database

Response

200 OK
Content-Type: application/json

Sample Response Body

[
    {
        "schema": <value>,
        "graphName": <value>
    }
]

Note that the schema parameter will be NULL for graphs created in the graph server (PGX).

cURL Example

curl --location --request GET 'https://localhost:7007/v2/graphs?driver=<driver-value>' \
--header 'Authorization: Bearer <token>'

Parent topic: Graph Server REST API Version 2

19.1.4 Run a PGQL Query

POST https://localhost:7007/v2/runQuery

Run one or multiple statements for the specified driver.

Version: v2

Request

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Table 19-3 Request Body Parameters

Parameter	Type	Description	Required
`statements`	string [ ]	One or multiple statements	Yes
`driver`	string	Specifies the PGQL driver. The supported values are: `GRAPH_SERVER_PGX`: To run PGQL queries against the graph server (PGX) `PGQL_IN_DATABASE`: To run PGQL statements or queries against the database `SQL_IN_DATABASE`: To run graph queries against the database	Yes
`formatter`	string	The supported values are: DATASTUDIO GVT	Yes
`parameters`	object `dynamicSampling:` integer `parallel:` integer `start:` integer `size:` integer	Parameters include: Dynamic Sampling Value Degree of Parallelism Fetch size (= the number of rows) of the query result	Parameters are all optional. Default value for dynamic sampling is 2. Default value for parallelism depends on the `driver`. Default value for start is `0`. Default value for size is `100`.
`visualize`	boolean	Flag to set visualization	Optional. Default value is `true`.

Sample Request Body

{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_view )", 
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100
  },
  "visualize": true

Response

200 OK
Content-Type: application/json

Sample Response Body

{
    "results": [
        {
            "pgqlStatement": "DROP PROPERTY GRAPH TEST_GRAPH",
            "result": "Graph successfully dropped",
            "success": true,
            "error": null,
            "started": 1689656429130,
            "ended": 1689656429198
        },
        {
            "pgqlStatement": "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_view )",
            "result": "Graph successfully created",
            "success": true,
            "error": null,
            "started": 1689656429198,
            "ended": 1689656429458
        },
        {
            "pgqlStatement": "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1",
            "result": "{\"schema\":\"GRAPHUSER\",\"name\":\"TEST_GRAPH\",\"resultSetId\":\"\",\"graph\":{\"vertices\":[{\"id\":\"MALE(0)\",\"properties\":{\"AGE\":\"40\",\"BVAL\":\"Y\",\"LNAME\":\"Brown\",\"FNAME\":\"Bill\",\"PREFERENCES\":\"{ \\\"color\\\": \\\"blue\\\", \\\"number\\\": \\\"5\\\" }\",\"ID\":\"0\",\"TEXT\":\"the cat sat on the mat\",\"MVAL\":\"y\"}}],\"edges\":[],\"numResults\":1},\"table\":\"V\\nMALE(0)\"}",
            "success": true,
            "error": null,
            "started": 1689656429458,
            "ended": 1689656430029
        }
    ]
}

cURL Example

curl --location --request POST 'https://localhost:7007/v2/runQuery' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_view )",
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100  
  },
  "visualize": true
}'

Parent topic: Graph Server REST API Version 2

19.1.5 Get the Database Version

GET https://localhost:7007/v2/dbVersion

Get the database version to which the graph server is connected.

Version: v2

Request

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Response

200 OK
Content-Type: application/json

Sample Response Body

{
    "dbVersion": "23.0"
}

cURL Example


curl --location --request GET 'https://localhost:7007/v2/dbVersion' \
--header 'Authorization: Bearer <token>'

Parent topic: Graph Server REST API Version 2

19.1.6 Get User

GET https://localhost:7007/v2/user

Get the username that is currently connected to the graph server (username is attached to the token).

Version: v2

Request

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Response

200 OK
Content-Type: application/json

Sample Response Body

{
    "username": "graphuser"
}

cURL Example

curl --location --request GET 'https://localhost:7007/v2/user' \
--header 'Authorization: Bearer <token>'

Parent topic: Graph Server REST API Version 2

19.1.7 Asynchronous REST Endpoints

The graph server REST endpoints support cancellation of queries.

In order to be able to cancel queries, you need to send the query using the following asynchronous REST endpoints:

Parent topic: Graph Server REST API Version 2

19.1.7.1 Run an Asynchronous PGQL Query

POST https://localhost:7007/v2/runQueryAsync

Run a PGQL query asynchronously on a property graph.

Version: v2

Request

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Request Query Parameters: See Table 19-3 for details.

Sample Request Body

{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_view )", 
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100
  },
  "visualize": true

Response

202 OK
Content-Type: application/json

Sample Response Body

{
    "message": "Query execution started.",
    "result_id": 0
}

cURL Example

curl --location --request POST 'https://localhost:7007/v2/runQueryAsync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "statements": [
    "DROP PROPERTY GRAPH TEST_GRAPH",
    "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_view )",
    "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100  
  },
  "visualize": true
}'

Parent topic: Asynchronous REST Endpoints

19.1.7.2 Check Asynchronous Query Completion

GET https://localhost:7007/v2/isAsyncQueryExecutionComplete/<result_id>

Check if an asynchronous query execution is completed.

Version: v2

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Request Path Parameter:

result_id: PGQL query execution result id.

Response

200 OK
Content-Type: application/json

Sample Response Body

true

cURL Example

curl --location --request GET 'https://localhost:7007/v2/isAsyncQueryExecutionComplete/<result-id>' \
--header 'Authorization: Bearer <token>'

Parent topic: Asynchronous REST Endpoints

19.1.7.3 Retrieve Asynchronous Query Result

GET https://localhost:7007/v2/runQueryAsync/<result_id>

Retreive the result of an asynchronous query.

Version: v2

Request

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Request Path Parameter:

result_id: PGQL query execution result id.

Response

200 OK
Content-Type: application/json

Sample Response Body

{
    "results": [
        {
            "pgqlStatement": "DROP PROPERTY GRAPH TEST_GRAPH",
            "result": "Graph successfully dropped",
            "success": true,
            "error": null,
            "started": 1689656429130,
            "ended": 1689656429198
        },
        {
            "pgqlStatement": "CREATE PROPERTY GRAPH TEST_GRAPH VERTEX TABLES( Male KEY (id) LABEL Male PROPERTIES ARE ALL COLUMNS EXCEPT (gender), Female KEY (id) LABEL Female PROPERTIES ARE ALL COLUMNS EXCEPT (gender) ) EDGE TABLES( knowsmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), knowsfm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL knows PROPERTIES (mval, firstMetAt, since), knowsff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL knows PROPERTIES (mval, firstMetAt, since), friendOfmm KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfmf KEY (id) SOURCE KEY (sid) REFERENCES Male DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength), friendOffm KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Male LABEL friendOf PROPERTIES (strength), friendOfff KEY (id) SOURCE KEY (sid) REFERENCES Female DESTINATION KEY (did) REFERENCES Female LABEL friendOf PROPERTIES (strength) ) OPTIONS ( pg_view )",
            "result": "Graph successfully created",
            "success": true,
            "error": null,
            "started": 1689656429198,
            "ended": 1689656429458
        },
        {
            "pgqlStatement": "SELECT v FROM MATCH (v) ON TEST_GRAPH LIMIT 1",
            "result": "{\"schema\":\"GRAPHUSER\",\"name\":\"TEST_GRAPH\",\"resultSetId\":\"\",\"graph\":{\"vertices\":[{\"id\":\"MALE(0)\",\"properties\":{\"AGE\":\"40\",\"BVAL\":\"Y\",\"LNAME\":\"Brown\",\"FNAME\":\"Bill\",\"PREFERENCES\":\"{ \\\"color\\\": \\\"blue\\\", \\\"number\\\": \\\"5\\\" }\",\"ID\":\"0\",\"TEXT\":\"the cat sat on the mat\",\"MVAL\":\"y\"}}],\"edges\":[],\"numResults\":1},\"table\":\"V\\nMALE(0)\"}",
            "success": true,
            "error": null,
            "started": 1689656429458,
            "ended": 1689656430029
        }
    ]
}

cURL Example

curl --location --request GET 'https://localhost:7007/v2/runQueryAsync/<result-id>' \
--header 'Authorization: Bearer <token>'

Parent topic: Asynchronous REST Endpoints

19.1.7.4 Cancel an Asynchronous Query Execution

DELETE https://localhost:7007/v2/runQueryAsync/<result_id>

Cancel the execution of an asynchronous query.

Version: v2

Request

Request Header

Accept: application/json; charset=UTF-8
Header: Authorization: Bearer <token>
Content-Type: application/json

Request Path Parameter:

result_id: PGQL query execution result id.

Response

200 Accepted
Content-Type: application/json

cURL Example

curl --location --request DELETE 'https://localhost:7007/v2/runQueryAsync/<result-id>' /
--header 'Authorization: Bearer <token>'

Parent topic: Asynchronous REST Endpoints

19.2 Graph Server REST API Version 1

Learn about the graph server REST API version 1 (v1).

Parent topic: REST Endpoints for the Graph Server

19.2.1 Login

POST https://localhost:7007/ui/v1/login/

Version: v1

Authentication: Uses cookie-based authentication.

Table 19-4 Parameters

Parameter	Parameter Type	Value	Required
`Content-type`	Header	`application/json`	Yes
`username`	Body	`<username>`	Yes
`password`	Body	`<password>`	Yes
`baseUrl`	Body	`<baseUrl>` to point to the graph server (PGX) or the database	Optional. If empty, the `pgx.base_url` parameter value in the `web.xml` file in `/opt/oracle/graph/pgx/server/graph-server-webapp-23.3.0.war` will be used.
`pgqlDriver`	Body	Valid PGQL driver configuration values are: `pgxDriver` : for PGQL on the graph server (PGX) `pgqlDriver`: for PGQL on Oracle Database	Yes
`sessionId`	Body	`sessionId` from graph server (PGX)	Optional

Request

The following curl command signs the user in to the graph server:

curl --cacert /etc/oracle/graph/ca_certificate.pem -c cookie.txt -X POST -H "Content-Type: application/json" -d '{"username": "<username>", "password": "<password>", "pgqlDriver": "<pgqlDriver>","baseUrl": "<baseUrl>", "sessionId": "<sessionId>" }' https://localhost:7007/ui/v1/login/

Response: The username used for the login. For example:

"oracle"

On successful login, the server session cookie is stored in a cookie file, cookie.txt. Use this cookie file, in the subsequent calls to the API.

Parent topic: Graph Server REST API Version 1

19.2.2 Get Graphs

GET https://localhost:7007/ui/v1/graphs

Get the list of all graphs that belong to a user.

Version: v1

Request

The following curl command lists all the graphs that belong to the user:

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/graphs'

Response: The list of graphs available for the current user. For example:

[
  {
    "schema": "HR",
    "graphName": "MY_GRAPH"
  }
]

Also, note that the schema parameter will be NULL for graphs created in the graph server (PGX).

Parent topic: Graph Server REST API Version 1

19.2.3 Run a PGQL Query

POST https://localhost:7007/ui/v1/query

Run a PGQL Query on a property graph.

Version: v1

Table 19-5 Request Query Parameters

Parameter	Description	Values	Required
`pgql`	PGQL query string	`<PGQL_query>`	Yes
`graph`	Name of the graph	`<graph_name>`	Optional, only if the `pgql` query parameter contains the graph name. Otherwise, it is required.
`parallelism`	Degree of Parallelism	`<parallelism_value>`	Optional. Default value depends on the PGQL driver configuration: `pgxDriver`: `<number-of-cpus>` See `parallelism` in Table 22-1. `pgqlDriver`: `1`
`size`	Fetch size (= the number of rows) of the query result	`<size_value>`	Optional. Default size value is `100`.
`formatter`	Formatter of the graph	`<formatter_value>`	Optional. Supported formatter options are: `datastudio` `gvt` Default value is `datastudio`.

Request

The following curl command executes PGQL Query on a property graph:

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr&size=100'

Response: The PGQL query result in JSON format.

{
  "name": "bank_graph_analytics_2",
  "resultSetId": "pgql_14",
  "graph": {
    "idType": "number",
    "vertices": [
      {
        "_id": "1",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_1"
        ]
      },
      {
        "_id": "418",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      },
      {
        "_id": "259",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      }
    ],
    "edges": [
      {
        "_id": "0",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "259",
        "u": false
      },
      {
        "_id": "1",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "418",
        "u": false
      }
    ],
    "paths": [],
    "totalNumResults": 2
  },
  "table": "e\nPgxEdge[provider=Transfers,ID=0]\nPgxEdge[provider=Transfers,ID=1]"
}

Parent topic: Graph Server REST API Version 1

19.2.4 Get User

GET https://localhost:7007/ui/v1/user

Get the name of the current user.

Version: v1

Request

The following curl command gets the name of the current user:

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/user'

Response: The name of the current user. For example:

"oracle"

Parent topic: Graph Server REST API Version 1

19.2.5 Logout

POST https://localhost:7007/ui/v1/logout/

Log out from the graph server.

Version: v1

Request

The following curl command is to successfully log out from the graph server.

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt -X POST 'https://localhost:7007/ui/v1/logout/'

Response: None

On successful logout, the server returns HTTP status code 200 and the session token from the cookie.txt file will no longer be valid.

Parent topic: Graph Server REST API Version 1

19.2.6 Asynchronous REST Endpoints

The graph server REST endpoints support cancellation of queries.

In order to be able to cancel queries, you need to send the query using the following asynchronous REST endpoints:

Parent topic: Graph Server REST API Version 1

19.2.6.1 Run an Asynchronous PGQL Query

GET https://localhost:7007/ui/v1/async-query

Run a PGQL query asynchronously on a property graph.

Version: 1

See Table 19-5 for more information on query parameters.

Request

The following curl command executes a PGQL query asynchronously on a property graph:

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr&parallelism=&size=100'

Response: None.

Note:

An error message will be returned in case the query is malformed or if the graph does not exist.

Parent topic: Asynchronous REST Endpoints

19.2.6.2 Check Asynchronous Query Completion

GET https://localhost:7007/ui/v1/async-query-complete

Checks if an asynchronous query execution is completed.

Version: v1

Request

The following curl command checks if the PGQL query execution is completed:

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query-complete'

Response: A boolean that indicates if the query execution is completed. For example,

true

Note:

You do not have to specify any request ID, as the currently executing query is attached to your HTTP session. You can only have one query executing per session. For concurrent query execution, create multiple HTTP sessions by logging in multiple times.

Parent topic: Asynchronous REST Endpoints

19.2.6.3 Retrieve Asynchronous Query Result

GET https://localhost:7007/ui/v1/async-result

Retreive the result of an asynchronous query.

Version: v1

Note:

The endpoint,

GET
          https://localhost:7007/ui/v1/async-result

to retrieve a query result is deprecated:

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-result?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr&parallelism=&size=100'

Request

The following curl command retrieves the result of a successfully completed query:

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-result'

Response: The PGQL query result in JSON format.

{
  "name": "bank_graph_analytics_2",
  "resultSetId": "pgql_14",
  "graph": {
    "idType": "number",
    "vertices": [
      {
        "_id": "1",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_1"
        ]
      },
      {
        "_id": "418",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      },
      {
        "_id": "259",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      }
    ],
    "edges": [
      {
        "_id": "0",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "259",
        "u": false
      },
      {
        "_id": "1",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "418",
        "u": false
      }
    ],
    "paths": [],
    "totalNumResults": 2
  },
  "table": "e\nPgxEdge[provider=Transfers,ID=0]\nPgxEdge[provider=Transfers,ID=1]"
}

Parent topic: Asynchronous REST Endpoints

19.2.6.4 Cancel an Asynchronous Query Execution

DELETE https://localhost:7007/ui/v1/async-query

Cancels the execution of an asynchronous query.

Version: 1

Request

The following curl command cancels a currently executing PGQL Query on a property graph:

curl -X DELETE --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query'

Response: Confirmation of the cancellation or an error message if the query has already completed execution.

Parent topic: Asynchronous REST Endpoints