Graph Server REST API Version 1

19.2.1 Login

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

Login to the graph server.

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-24.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 23-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