How to Use the KNIME Business Hub REST API

In today’s IT landscape, integrating across applications is standard practice—and REST APIs make that easier. Here we give you a hands-on guide to getting started with the KNIME Business Hub REST API and show you how to invoke a workflow.

If you're looking for info on REST with KNIME Server, check out this guide on the KNIME Server REST API.

REST has become one the most predominant architectures for obtaining and managing data across applications in the modern IT world. REST protocols are generally stateless, lightweight, robust, and easy to work with. That makes them a great choice for KNIME Business Hub's communication in a modern, data-driven organization.

We can use the KNIME Business Hub REST API to allow external applications to invoke workflows, but also to manage KNIME Business Hub installation itself, with regards to users and teams, execution contexts, instrumentation, permissions, and much more.

Popular use cases for workflows deployed as a REST service on a KNIME Business Hub include:

• Trigger workflows to perform ETL e.g. move data into a visualization tool like Tableau from a database
• Return model predictions for given input data

You could also also search the content of a KNIME Business Hub via REST. However, this blog focuses on how to generally invoke a workflow.

Here's how.

You can use several tools to invoke REST endpoints such as: curl, SoapUI, Postman, or KNIME Analytics Platform.

In this article, we’ll be using Postman, because it has the capacity to output REST invocations in different formats including curl, Java, Python, R, and has the capacity to manage collections of APIs.

Similar to KNIME Server, KNIME Business Hub provides a Swagger interface for its REST endpoints, which makes finding and using REST services simple.

You'll find the KNIME Business Hub REST API interface at: api.<base-url>/api-doc/

• For example, if your KNIME Business Hub is hosted at hub.example.com, you'll find the REST API documentation at api.hub.example.com/api-doc/ .

• You'll see something like this:

From here, we can drill down into the sections below and find the available REST endpoints. Note that they are color-coded by invocation type (GET, POST, PUT, and DELETE).

The available list of services may vary depending on how your KNIME Business Hub is configured, however many will be the same.

For example:

• Under ‘accounts-service’ you can retrieve information about all the accounts on your KNIME Business Hub.
• Under ‘catalog-service’ you can find the repository, nodes, and extensions
• Under 'search-service' you can perform searches on workflows and nodes

We're going to focus on the 'Jobs' section in 'execution-service'.

Drill down into one of the REST endpoints, such as the GET /jobs endpoint. It returns all jobs that are managed by this service to see a description of the endpoint plus all optional parameters and filters.

If we look at one of the POST or PUT calls, at at /jobs/{uuid} we can also see an example for the Request body that we would send with the request.

Several of our endpoints in the ‘Jobs’ section contains a ‘{path}’ or ‘{uuid}’ in the request.

The brackets denote that this is a variable we need to find and append to the request.

Many tools, such as Postman, allow for creating collections of REST requests to help with managing requests. We can import templates for the REST API endpoints of the individual services of KNIME Business Hub by clicking the link under the service dropdown, and importing the downloaded openapi file into Postman.

Alternatively you can take the openapi URL and append it with '.json' to see the JSON in the browser.

There are two ways to invoke a KNIME workflow via REST requests: a single-step method, and a multi-step method.

• The single-step method uses the ‘execution’ endpoint and instantly creates, runs, and discards a job.
• The multi-step method, ‘jobs’, loads a job and then requires a separate request to trigger and keep the completed job, so you can re-execute or view from KNIME Analytics Platform and the WebPortal

The easiest way to find the endpoints for a specific workflow is by navigating to the deployment of that workflow on KNIME Business Hub, then clicking the three dots on the right, and selecting 'Open API docs'. This opens a new browser tab for that specific workflow. , right-clicking it, and selecting “Show API Definition”. This opens a new browser tab for that specific workflow.

In our example, here, the workflow is called 'JSON input callee'.

Notice that there are drop-downs for Execution and Jobs. Both contain their own GET and POST requests.

We'll use the POST requests here for each of them to provide a more comprehensive overview.

There are two ways you can authenticate against KNIME Business Hub REST API endpoints:

• JWT
• Basic authentication

Here we'll use basic authentication for simplicity. All you need is an application password of your account in KNIME Business Hub! You can find instructions how to create one in our documentation

Now that we have our REST endpoints, we can start executing the workflows. To execute the workflows in Postman we create a new request and start filling some things out.

Let’s start with our single step execution to discard the job.

There are two ways to retrieve the Request URL

The first way is to open the drop-down menu in the Swagger UI, click “Try it out” and subsequently “Execute” and you will be shown the Request URL that you can simply copy.

The second way is to join the endpoint as shown in the header to the base URL of your Business Hub with an api prefix.

In our example:

• The header is: /deployments/rest:09f4b20b-be77-45c8-8cd3-9b0658fbb5c1/execution
• The base URL is https://api.hub.example.com
• This results in: https://api.hub.example.com/deployments/rest:09f4b20b-be77-45c8-8cd3-9b0658fbb5c1/execution

Once you've found the Request URL, create a new POST Request in Postman and paste the Request URL on top.

Next, enter your application password in the Authorization tab after you choose “Basic Auth”.

Now switch to the Body tab.

The JSON body (for which you’ll find an example in the Swagger UI) is where the input data can be customized for this run.

Click the Send button on the right side to get a response that contains metadata, how the execution went, plus any output data with the workflow!

You might have noticed that with the ‘execution’ endpoint our job is automatically discarded, and we can’t see or inspect it on the deployment webpage of KNIME Business Hub.

If we want our job to persist we can use the multi-step method. This method load sthe job and then allow us to execute it at a separate time. This is particularly useful if we want to load several jobs in preparation of some number of anticipated requests.

To retrieve the Request URL, you can either proceed as described in the Single-Step Execution section by clicking “Try it out” and “Execute” and copying the shown Request URL, or by joining the endpoint from the header to your KNIME Business Hub’s api endpoint (for example https://api.hub.example.com/deployments/rest:09f4b20b-be77-45c8-8cd3-9b0658fbb5c1/jobs). Note that the ending is jobs instead of execution this time!

Back in Postman, we can insert the Request URL for a POST request, and again provide authorization as described above. The body will stay empty this time, as we are not sending any data input.

This time, our workflow didn’t actually execute, but it loaded a job with an UUID that you can also see in the browser.

To actually execute this job, we need to find the ‘knime:execute-job’ object in the JSON response and grab the link it contains.

This link is calling a different ‘job’ API by the UUID of the job we just loaded.

We can take note of the method that this link needs, as well as the template for the request. This link contains any optional parameter at the end, which we’ll remove for now to give us a new POST endpoint that we can call to execute the job as so.

You can provide input data in the JSON body. The response of this call will return you the results or error messages of nodes that failed. You can also inspect the executed job in the browser.

You now know how to execute workflows via a REST API.

The KNIME Business Hub REST API is available as part of KNIME Business Hub. For more information or to arrange a trial, contact  KNIME Customer Care.