Oracle Graph Server REST API

Oracle Graph is a powerful tool designed to uncover hidden relationships within your data. By representing information in a graph structure, Oracle Graph enables organizations to gain valuable insights from interconnected data entities. The Oracle Graph offering includes the Graph Server REST API, a gateway to utilize the capabilities of Oracle Graph from any application with a simple REST call. This API allows developers to interact with their graphs, enabling them to create graphs, run queries, and derive actionable information from their data

Oracle Graph REST API v1 employs cookie-based authentication and encodes queries within URLs. In Oracle Graph Server and Client release 23.3 we released Oracle Graph REST API v2, which adopts token-based authentication and allows queries to be transmitted within the JSON body. The Graph Server REST API provides a vital resource for developers to easily create and query graphs.

Background for the following examples:

• Oracle Graph includes the ability to run graph queries in Oracle Database, and also run graph queries and analytics in a specialized in-memory Graph Server (PGX).  
• To load data from the bank_graph example and create a graph, refer to this github repository.

Graph Server REST API v2

Let’s run through a simple example using version 2 of the Graph Server REST API with Postman. For all of the following API calls, ensure that the request has the following headers:

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

1. Get Authentication Token

Create a POST request to https://<Graph_Server_IP>:7007/auth/token. Add a JSON body with the username, password and createSession parameters.

Set the createSession parameter to True if you want to create a PGX session to run queries in the in-memory Graph Server, or False if you are running queries in the database.

The response should be an access token, which we will use in the next API calls.

2. Get Graphs

Create a GET request to https:// <Graph_Server_IP>:7007/v2/graphs, with a query parameter for the driver you want to use (GRAPH_SERVER_PGX, PGQL_IN_DATABASE or SQL_IN_DATABASE). The resulting query string should look like https:// <Graph_Server_IP>:7007/v2/graphs?driver=pgql_in_database.

Add an Authorization header with the value 'Bearer <access_token>'.

The response should be a list of graphs for your authenticated user.

3. Run a Query

Create a POST request to https:// <Graph_Server_IP>:7007/v2/runQuery.

Add an Authorization header with the value 'Bearer <access_token>'.

Add a JSON body with the statements, driver, formatter, parameters and visualize parameters, following this example:

The result should be a JSON object with the result of the query run.

4. Refresh Access Token

To refresh your access token before it expires, create a PUT request to https://<Graph_Server_IP>:7007/auth/token.

Add a JSON body with token and createSession parameters. The token should have the value for the current access token. Set the createSession parameter to True if you want to create a PGX session to run queries in the in-memory Graph Server, or False if you are running queries in the database.

The response should be the new access token.

For more information on v2 of the Graph Server REST API and a full list of functionalities, visit the official documentation.

Graph Server REST API v1

Let’s run through a simple example using version 1 of the Graph Server REST API with Postman. For all of the following API calls, ensure that the request has the following headers:

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

1. Authenticate user

Create a POST request to https://<Graph_Server_IP>:7007/ui/v1/login/.

Add a JSON body with username, password, pgqlDriver and baseUrl parameters. The pgqlDriver parameter specifies if you want to connect to the database, using pgqlDriver, or to Graph Server, using pgxDriver. The baseUrl parameter should be the url of Graph Server if you are using the pgxDriver, or the JDBC url for your database if you are using the pgqlDriver.

The response should be the username of the user who has been authenticated. On successful login, the server session cookie is stored in a cookie file, cookie.txt.

2. List Graphs

Create a GET request to https://<Graph_Server_IP>:7007/ui/v1/graphs. The cookie should be automatically added as a header in Postman.

The response should be a list of graphs for your authenticated user.

3. Run Query

Create a Get request to https://<Graph_Server_IP>:7007/ui/v1/query, with pgql, graph, parallelism and size parameters. The resulting url should look like:

https://<Graph_Server_IP>:7007/ui/v1/query?pgql=<PGQL_query>&graph=<graph_name>&parallelism= <parallelism_value>&size=<size>

For example to query five edges from bank_graph, we can use the following: https://<Graph_Server_IP>:7007/ui/v1/query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=BANK_GRAPH&parallelism=&size=100

The result should include the resulting vertices and edges queried in a JSON format.

4. Logout of Graph Server

Create a POST request to https://<Graph_Server_IP>:7007/ui/v1/logout/.

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

For more information on v1 of the Graph Server REST API and a full list of functionalities, visit the official documentation.