Technical information

Introduction

GraphQL is a query language and runtime environment for APIs. Unlike REST, GraphQL allows clients to request only the specific data they need, avoiding overfetching and underfetching, thus improving data transfer efficiency. With its type system and query structures, GraphQL offers a flexible and powerful way to exchange data between client and server.

Many people already know that a consumption of a GraphQL API is possible via the apex_web_service package in PL/SQL. However, there is also a way to do this declaratively in Oracle APEX.

Easy way with PL/SQL

With PL/SQL it is very easy to consume a GraphQL API using the function apex_web_service.make_rest_request. You construct an HTTP POST request to the GraphQL endpoint, specifying the GraphQL query or mutation in the request body. You then handle the response returned by the API, typically in JSON format, within your APEX application, parsing and processing the data as needed. This method allows you to interact with GraphQL APIs directly from your APEX application's PL/SQL code.

But can we not also do this declaratively in APEX? This has not yet been documented so far, but there is a very simple trick that I would like to explain below.

Do it declaratively in the APEX backend

To be able to use a GraphQL API in Oracle APEX as a REST data source, we have to trick it a little bit.

The first steps are analogue to a simple REST API.

On the Authentication page of the wizard, it is now important not to click on Discover.

In this case, our new "REST Data Source" would be tested before it is created, which can lead to various errors ("GET query missing", "HTTP Error - Unknown", error of the API itself, etc.). 

There are several reasons for this: A GraphQL API is always addressed with a POST method, whereby the request body contains the corresponding GraphQL query. This is also used to fetch rows. Such a POST method can be created under Advanced. However, this is defined by default as "insert row" instead of "fetch rows". APEX creates a GET for the "fetch rows" by default, but this is not supported by the GraphQL API.

We click on Create REST Source Manually instead to prevent this.

Now our GraphQL Data Source has been created. But we need to make a few more changes.

As we have created our GraphQL Data Source manually, all four HTTP methods are created automatically. We do not need DELETE, GET and PUT to consume a GraphQL API. These are dropped. However, our POST method must be modified.

To do this, it is important to know what our GraphQL query and its JSON response look like (see the following illustration).

In our case, we want to use the POST method to fetch data. So, we set the database operation to "fetch rows".

In the request body template, we insert our JSON body that is to be sent to the API. Attention: Paragraphs can lead to errors here.

Next, we modify the data profile.

The row selector must be adapted according to the expected JSON response. The columns created by APEX by default are then deleted and our customized columns are added.

Now let's test it.

Yay! Successful!

Now we can use this new GraphQL Data Source using its POST method for our APEX components.

Utilise the dynamic magic of GraphQL

We are using GraphQL, which actually stands for dynamism. So, the example shown above is really for showing that the connection to a GraphQL API works declaratively. But can we also make the whole thing dynamic? Of course we can!

To do this, we change our POST method once again

 

Set the Request Body Template to a substitution string, for example #body# and let it map to an operation parameter.

The corresponding parameter can then be used in the Page Designer and be set dynamically. It is important that the corresponding value type returns a JSON object that contains the correct GraphQL query.

And now we can use our GraphQL data source within our components.

Implement a GraphQL API with ORDS 23.3

As a small hint: Since ORDS 23.3 it is now also possible to implement GraphQL APIs with Oracle Database. Jeff Smith has written an excellent article about this: https://www.thatjeffsmith.com/archive/2023/10/ords-23-3-is-now-available-or-hello-graphql/

Comments

No Comments

Write comment

* These fields are required

Related Posts