Skip to Content
Technical Articles
Author's profile photo Cameron Swift

SAP Data Intelligence Cloud – OpenAPI Client Basics

This blog post is written in collaboration with the SAP HANA Database & Analytics, Cross Product Management team – thanks to my colleague Wei Han for her help in reviewing this post

Using the SAP Data Intelligence Modeler, we can create pipelines (graphs) to work with data from a number of sources. One of the first things you may want to try when creating your first pipeline is retrieving data via an API

In this brief blog post, we’ll cover the basics of using the OpenAPI Client operator to retrieve data from a Qualtrics API – List Surveys. Once you understand the basics of working with the OpenAPI Client operator, you should be equipped to retrieve data from other API sources

 

Our API Request

 

By default, the Qualtrics API Reference presents a sample API Request for Shell/cURL (the value in X-API-TOKEN is a stand-in for your individual Qualtrics API Token)

Sample%20API%20Request

Sample API Request

 

At time of writing, the OpenAPI Client operator uses the OpenAPI 2.0 specification (formerly known as Swagger 2.0 specification). In this blog post, we will demonstrate how to map our Qualtrics API Request to this specification, however any further exploration of the OpenAPI specification is considered out of scope

 

Configuring the OpenAPI Client

 

First, we start by placing an OpenAPI Client operator on a new graph

OpenAPI%20Client%20operator%20can%20be%20found%20under%20Connectivity

OpenAPI Client operator can be found under Connectivity

 

Next we will map the Sample API request to the fields of our OpenAPI Client operator. A visual breakdown is included below

Each%20box%20represents%20a%20parameter%20in%20our%20OpenAPI%20Client%20operator

Each box represents a parameter in our OpenAPI Client operator

 

First, we will select the OpenAPI Client operator, and set the value of Authentication Scheme to apiKey

Setting%20the%20Authentication%20Scheme%20to%20apiKey

Setting the Authentication Scheme to apiKey

 

Setting the Authentication Scheme will allow you to enter values for API Key Name, Type and Value. API Type can be either Header or Query. As we can see from our sample request, the API Key should be sent in the Header. The expected name for the API Key is “X-API-TOKEN”

We can retrieve our API Token Value from Qualtrics. We do this by navigating to Account Settings -> Qualtrics IDs ->IDs

Demo%20text

Retrieving our Qualtrics API Token

 

With our API Key Value retrieved, the Authentication Scheme configuration is complete and should look like the following:

Our%20Authentication%20Schema%20configuration

Our Authentication Schema configuration

 

In our case, the values required for Method and Produces are correct by default – we are making a GET request, and the result is expected in the application/json format. Neither of these values need to be changed

Next, we’re going to fill out the configuration to specify the correct values of Schemes, Hostand Base Path

Schemes specifies the transfer protocol of the API. In our case, the protocol used is https

Host is used to specify the host (name or IP) serving the API. This does not include the scheme or sub-path, but may include the port. For this example, our host is ca1.qualtrics.com

Base Path specifies the base path where the API is served, which is relative to the host. It must begin with a leading slash (/). We want to enter /API/v3/surveys

Once we’ve set these, our configuration should look like the below

Schemes%2C%20Host%2C%20and%20Base%20Path%20are%20set

Schemes, Host, and Base Path are set

 

Completing our Graph

 

At this point, all of the necessary configuration of the OpenAPI Client operator has been completed. The operator will make a request when it receives input to its input port

In order for our example to trigger the API Call exactly once, we will place a Workflow Trigger operator into the graph, and connect its output port to the input port of our OpenAPI Client operator

In order to read the API response, we connect the output port of our OpenAPI Client operator to a Wiretap operator. Our graph is now ready to be tested

Our%20finished%20graph

Our finished graph

Save and run your graph, then select the Wiretap operator and click on the Open UI symbol to check the output

Our%20Wiretap%20Output%20shows%20that%20our%20request%20is%20successful

Our Wiretap Output shows that our request is successful

 

Creating our API Connection

 

Once we’ve verified that everything is working we have one final step before we move on. While using the manual connection mode in our operators is fine while building our graphs, before any of our graphs make it into production we want to use a connection created within Connection Management. This allows for centralized management of the connection if, for example you rely on more than one API which uses the same connection details

From the Data Intelligence Launchpad, select Connection Management then click on the Create Connection button

Click%20to%20create%20a%20new%20Connection

Click to create a new Connection

 

For the Connection Type, we want to choose OpenAPI, then we want to select ApiKey as our Authentication Type, and fill out the values for ID, Host, Protocol (OpenAPI Scheme), API Key Name, API Key Type and API Key Value

Creating%20the%20connection%20in%20Connection%20Management

Creating the connection in Connection Management

Once you’ve entered all of the necessary details, click Create and return to the Modeler. Change the value of Connection Type to connection, then edit the Connection Property as shown to select the Connection we just created

Editing%20the%20Connection%20property

Editing the Connection property

Once we’ve changed the Connection Type and Connection property, we verify that our pipeline returns the results as expected by running it and checking the Wiretap output again

In this blog post, we’ve covered how we can use an OpenAPI Client operator to make an API request, and verify the response data in a Wiretap operator. We can store these results in a table in HANA, and use them in combination with other APIs (for example, retrieving responses for individual surveys) for modeling or analytics

This blog post may naturally lead to follow up questions, such as “What if I need to pass in additional parameters”, or “What if I want to dynamically change the values of parameters?”. I hope to cover these questions in future blog posts

I hope this blog post has been useful, and I welcome any comments or questions below

Assigned tags

      Be the first to leave a comment
      You must be Logged on to comment or reply to a post.