Enabling graphQL on ORDS

In today’s data-driven world, the need for flexible and efficient data querying solutions has never been greater. Traditional REST APIs have served us well, but they often fall short in scenarios requiring more granular data fetching. With GraphQL, a powerful query language for APIs that allows clients to request exactly the data they need. Combining GraphQL with Oracle REST Data Services (ORDS) can unlock new potentials for data retrieval and manipulation. In this blog, we’ll explore how to set up and use GraphQL with ORDS.

What is GraphQL?

GraphQL, developed by Facebook in 2012 and open-sourced in 2015, is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. Unlike REST, GraphQL allows clients to request only the data they need, which can reduce the amount of data transferred over the network and improve performance.

What is Oracle REST Data Services?

Oracle REST Data Services (ORDS) is a mid-tier Java application that enables developers to expose data from Oracle databases via RESTful web services. ORDS simplifies the process of creating and managing RESTful services and can serve as a bridge to modern web and mobile applications.

Why Use GraphQL with ORDS?

Starting with ORDS version 23.3 you can now leverage the flexibility of GraphQL. This integration allows developers to create more efficient and responsive applications by leveraging GraphQL’s precise data fetching capabilities and ORDS’s robust database interactions.

Setting Up GraphQL with ORDS

Here’s a step-by-step guide to setting up GraphQL with Oracle REST Data Services.

Prerequisites: Ensure you have access to an Oracle Database instance.

Download and Install GraalVM JDK17.
Download and Install JavaScript support for GraalVM.
ORDS: Install and configure ORDS (23.3 version or higher).
Enable Rest API for schema.
Access GraphiQL

Step 1: Download and Install GraalVM EE for JDK17.

GraaVM is available from different platforms like Linux, macOS, Windows and Docker Container. For this particular exercise, I used Linux operating system.

1. Navigate to GraalVM Download Page. Select 17 for the java version and your operating system. For this particular step, I used Linux operating system.
2. Change to directory where you want to install GraalVM, then move the .tar.gz file to that directory.
3. Unzip the archive using the command below: tar -xzf graalvm-jdk-<version>_linux-<architecture>.tar.gz
4. There can be multiple JDKs installed on the machine. The next step is to configure the runtime environment
  1. 1. Set the value of the JAVA_HOME environment variable to the installation directory:
  b. export JAVA_HOME=/path/to/<graalvm>
  1. 1. Set the value of the PATH environment variable to the GraalVM bin directory:
  d. export PATH=/path/to/<graalvm>/bin:$PATH

To confirm that the installation was successful, run the java -version command.

You may want to edit your bachrc file to permanently set this JAVA_HOME and PATH variables.

Step 2: Download and Install JavaScript support for GraalVM

GraphQL engine is written in server-side JavaScript, to enable this we need to add additional component. You can install it over the internet or manually.

If your machine has access to internet, the “Graal Updater” from the GraalVM JDK17 can be used to install it using the command below.

gu install js

In all other cases, select “JavaScript Runtime” on the GraalVM download page, install the file locally:

gu -L install js-installable-svm-svmee-java17-windows-amd64-22.3.1.jar (or other version number)

Use the gu list to see all the components installed on the machine.

Step 3: Install and configure ORDS (23.3 version or higher)

Navigate and download the ORDS using this Oracle download page. Before you start installation, add the following from the settings.xml file from the ORDS config file. This is to make sure that it will use the GraalVM to run the ORDS.

Execute the following to start installation and follow the prompt. ords –config /oracle/home/ords_config install

Step 3: Enable REST API for Schema

Connect to database using SQL Developer, right click on the schema name and choose REST Services -> Enable REST Services.

Or you can activate it using the following SQL:

				
					BEGIN
   ORDS.ENABLE_SCHEMA(p_enabled => TRUE,
                      p_schema => 'HR', );
END;
/

Now activate the HR tables for REST Access. Right click on the table and then click Enable REST Services.

Do it for all the tables that you wanted to expose through REST API.

Or you can run PL/SQL below to do the same via script.

				
					BEGIN
  ORDS.enable_object ( p_schema => 'HR', p_object => 'EMPLOYEES', p_object_alias => 'employees');
  ORDS.enable_object ( p_schema => 'HR', p_object => 'DEPARTMENTS', p_object_alias => 'departments'); 
  ORDS.enable_object ( p_schema => 'HR', p_object => 'LOCATIONS', p_object_alias => 'locations');     
  COMMIT;
END;

Step 6: Access and run query from GraphiQL

Using the browser, a call to the following URL opens the graphiQL.

http://<server>:<port>/ords/<schema>/_/graphiql/

e.g. http://localhost:8080/ords/hr/_graphiql

Now, it is all set up and you can your query from graphiQL.