1. Graph Developer's Guide for Property Graph
  2. Using the Graph Server (PGX)
  3. REST Endpoints for the Graph Server

17 REST Endpoints for the Graph Server

This section explains the Graph Server REST endpoints:

The following are the available REST endpoints:

Note:

The examples shown in the REST endpoints assume that:

  • The PGX server is up and running on https://localhost:7007.
  • Linux with cURL is installed. cURL is used to demonstrate how to access the graph.publish API using the CA certificate for verifying the graph server.

Parent topic: Using the Graph Server (PGX)

17.1 Login

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

Authentication: Uses cookie-based authentication.

Table 17-1 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 will be used. See Table 18-1 for the location of the web.xml file.
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: REST Endpoints for the Graph Server

17.2 List Graphs

GET /v2/graphs

HTTP Request: GET https://localhost:7007/ui/v2/graphs

Request

The following curl command lists all the graphs to which the user has access along with the schema information: 

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

Response: The list of graphs available for the current user along with the schema details. For example: 

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

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

GET /v1/graphs

Note:

The /v1/graphs endpoint may be deprecated in a future release of Graph Server and Client. Therefore, it is recommended that you use the /v2/graphs endpoint to list all the graphs for a user.
HTTP Request: GET https://localhost:7007/ui/v1/graphs

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: 

["hr", "bank_graph_analytics"]

Parent topic: REST Endpoints for the Graph Server

17.3 Run a PGQL Query

HTTP Request: GET https://localhost:7007/ui/v1/query?pgql=<PGQL_query>&graph=<graph_name>&parallelism=<parallelism_value>&size=<size_value>&formatter=<formatter_value>

Table 17-2 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 20-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: REST Endpoints for the Graph Server

17.4 Get User

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

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: REST Endpoints for the Graph Server

17.5 Logout

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

Request

The following curl command is to successfully log out from the Graph Visualization application: 

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: REST Endpoints for the Graph Server

17.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: REST Endpoints for the Graph Server

17.6.1 Run a PGQL Query Asynchronously

HTTP Request: GET https://localhost:7007/ui/v1/async-query?pgql=<PGQL query>&graph=<graph>&parallelism=<value>&size=<size value>

See Table 17-2 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

17.6.2 Check a Query Completion

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

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

17.6.3 Cancel a Query Execution

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

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

17.6.4 Retrieve a Query Result

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

Note:

The endpoint, GET https://localhost:7007/ui/v1/async-result?pgql=<PGQL query>&graph=<graph>&parallelism=<value>&size=<size value>, 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