Skip to content

REST Clients

Jump to bottom
assimbly edited this page May 17, 2022 · 9 revisions

Assimbly is an API-driven application. This means almost any action can be performed by calling a REST API endpoint. These actions are for example called when you click on the button in the user interface. Most actions in the GUI can also be performed by a REST client.

Example REST Clients

Online (Swagger)

The easiest way to call an API endpoint is through the Swagger documentation (OpenAPI 3.0 is used). An overview of all REST endpoints can be found on the following page:

Administration --> API

The user needs admin rights to see the "Administration" menu. On the API page all REST endpoints are documented by Swagger where you can also try every endpoint. Technically Assimbly uses JWT (JSON Web Token) provided by JHipster. More details on this mechanism can be found here:

https://www.jhipster.tech/security/

Command line (CURL)

In this section we are using the REST API to start a flow. For this we use the external REST client CURL to make the API calls.

Using Clients (3.6.0 and above)

Here are two examples that set the XML configuration and start a flow. The used "urls", "integration id" and "flow id" can change per flow/gateway.

cURL example

Step 1: Set configuration

curl -X 'POST' \
  'http://localhost:8088/api/integration/1/setflowconfiguration/1' \
  -H 'accept: application/xml' \
  -H 'Content-Type: application/xml' \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<integrations>
   <version>3.6.0</version>
   <integration>
      <id>1</id>
      <name>default</name>
      <type>FULL</type>
      <type>Dev1</type>
      <stage>DEVELOPMENT</stage>
      <defaultFromComponentType>file</defaultFromComponentType>
      <defaultToComponentType>file</defaultToComponentType>
      <defaultErrorComponentType>file</defaultErrorComponentType>
      <flows>
         <flow>
            <id>1</id>
            <name>TestFlow</name>
            <type>connector</type>
            <version>2</version>
            <created>2022-05-13T07:26:39.435Z</created>
            <lastModified>2022-05-13T08:52:58.949Z</lastModified>
            <autostart>false</autostart>
            <assimblyHeaders>true</assimblyHeaders>
            <parallelProcessing>true</parallelProcessing>
            <maximumRedeliveries>0</maximumRedeliveries>
            <redeliveryDelay>3000</redeliveryDelay>
            <logLevel>OFF</logLevel>
            <notes/>
            <components>
               <component>file</component>
            </components>
            <endpoints>
               <endpoint>
                  <id>1</id>
                  <type>from</type>
                  <uri>file://C:\messages\in</uri>
               </endpoint>
               <endpoint>
                  <id>2</id>
                  <type>to</type>
                  <uri>file://C:\messages\out2</uri>
               </endpoint>
               <endpoint>
                  <id>3</id>
                  <type>error</type>
                  <uri>file://C:\messages\error</uri>
               </endpoint>
            </endpoints>
         </flow>
      </flows>
      <services/>
      <headers/>
      <routes/>
      <routeConfigurations/>
      <environmentVariables/>
   </integration>
</integrations>'

Step 2: Start flow

curl -X 'GET' \
  'http://localhost:8088/api/integration/1/flow/start/1' \
  -H 'accept: application/xml'

Using Postman

Step 1: Set configuration

<integrations>
   <version>3.6.0</version>
   <integration>
      <id>1</id>
      <name>default</name>
      <type>FULL</type>
      <type>Dev1</type>
      <stage>DEVELOPMENT</stage>
      <defaultFromComponentType>file</defaultFromComponentType>
      <defaultToComponentType>file</defaultToComponentType>
      <defaultErrorComponentType>file</defaultErrorComponentType>
      <flows>
         <flow>
            <id>1</id>
            <name>TestFlow</name>
            <type>connector</type>
            <version>2</version>
            <created>2022-05-13T07:26:39.435Z</created>
            <lastModified>2022-05-13T08:52:58.949Z</lastModified>
            <autostart>false</autostart>
            <assimblyHeaders>true</assimblyHeaders>
            <parallelProcessing>true</parallelProcessing>
            <maximumRedeliveries>0</maximumRedeliveries>
            <redeliveryDelay>3000</redeliveryDelay>
            <logLevel>OFF</logLevel>
            <notes/>
            <components>
               <component>file</component>
            </components>
            <endpoints>
               <endpoint>
                  <id>1</id>
                  <type>from</type>
                  <uri>file://C:\messages\in</uri>
               </endpoint>
               <endpoint>
                  <id>2</id>
                  <type>to</type>
                  <uri>file://C:\messages\out2</uri>
               </endpoint>
               <endpoint>
                  <id>3</id>
                  <type>error</type>
                  <uri>file://C:\messages\error</uri>
               </endpoint>
            </endpoints>
         </flow>
      </flows>
      <services/>
      <headers/>
      <routes/>
      <routeConfigurations/>
      <environmentVariables/>
   </integration>
</integrations>
  • Send

postman_setconfiguration

Step 2: Start flow

postman_startflow

Using Clients with older version (before 3.6.0)

Step 1: Get Cookie

First we make the following call:

curl -v --cookie-jar cookies.txt --cookie cookies.txt --header "Accept: application/json, text/plain, */*" --header "Content-Type: application/x-www-form-urlencoded" --request "POST" http://localhost:8080/api/authentication

This save the cookie to use in the following call. The text files looks like this:

# Netscape HTTP Cookie File
# https://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

#HttpOnly_localhost	FALSE	/	FALSE	0	JSESSIONID	MV9-w7XmySA00EZFKXPtIbhsj0jtTF_xDatbMjDI
localhost	FALSE	/	FALSE	0	XSRF-TOKEN	5f701449-c058-4e11-97e6-dfb6585fd0e8

Step 2: Authenticate

Copy XSRF token (in this example it is "5f701449-c058-4e11-97e6-dfb6585fd0e8") and replace {XSRF-TOKEN} by this value in the value url:

curl -v --cookie-jar cookies.txt --cookie cookies.txt --header "Accept: application/json, text/plain, */*" --header "Content-Type: application/x-www-form-urlencoded" --header "X-XSRF-TOKEN: {XSRF-TOKEN}" --data "j_username=admin&j_password=admin&remember-me=undefined&submit=Login" --request "POST" http://localhost:8080/api/authentication

Step 3: Call endpoints

Now you can call any endpoint. This example starts flow 1:

curl -v --cookie-jar cookies.txt --cookie cookies.txt --header "Accept: application/xml" --header "Content-Type: application/x-www-form-urlencoded" --request "GET" http://localhost:8080/api/connector/1/flow/start/1

Note that now you don't to set "X-XSRF-TOKEN" anymore

App or Webapp (Insomnia)

In this section we are using the REST API to start a flow. For this we use the external REST client Insomnia (https://insomnia.rest/download/) to make the API calls.

API Documentation

On the API overview page in Assimbly the complete API is documented with Swagger. Here you can first try every endpoint. It is recommended to try this before using an external client. When you try a REST endpoint a CURL statement is also shown. Unfortunately these CURL statements won't work out of the box. For example to start a flow the following request URL is used:

http://localhost:8080/api/connector/1/flow/start/1

The CURL is:

curl -X GET --header 'Accept: application/xml' --header 'X-XSRF-TOKEN: 2348be29-8895-4ad8-9544-c84e7b5dbb47' 'http://localhost:8080/api/connector/1/flow/start/1'

The response body is:

<response>
  <path>/connector/{connectorId}/flow/start/{id}</path>
  <details>succesful</details>
  <id>1</id>
  <message>started flow 1</message>
  <timestamp>2019-05-23 07:35:43.806</timestamp>
  <status>200</status>
</response>

However, when trying this from an external client the response body is as follows:

<response>
    <path>/api/connector/1/flow/stop/1</path>
    <details>failed. See the log for a complete stack trace</details>
    <id>0</id>
    <message>Full authentication is required to access this resource</message>
    <timestamp>2019-05-22 15:27:29.554</timestamp>
    <status>400</status>
</response>

To call any REST endpoint one first needs to be authenticated.

Step 1: Authentication

The first step is to authenticate the user. This can be done by an HTTP post to the following endpoint:

http://localhost:8080/api/authentication

Also the following HTTP headers needs to be set:

Accept: application/json, text/plain, */*
Content-Type: application/x-www-form-urlencoded
X-XSRF-TOKEN: 459db757-4d86-49de-baa2-9ac724f0fb32

To get the X-XSRF-TOKEN depends on the client. This token is mostly saved as a cookie by the client. For example Insomnia REST client:

https://support.insomnia.rest/article/49-cookies

The body of the message needs to have the login credentials:

j_username=admin&j_password=admin&remember-me=undefined&submit=Login

Example call:

> POST /api/authentication HTTP/1.1
> Host: localhost:8080
> User-Agent: insomnia/6.5.3
> Cookie: JSESSIONID=3UPoreZMv9BHCgGGSiienQjLzLCoQDhoa_4yqVx4; XSRF-TOKEN=936a9190-87f4-444b-9d36-8abf1fc65a7b; remember-me=
> Accept: application/xml
> X-XSRF-TOKEN: 936a9190-87f4-444b-9d36-8abf1fc65a7b
> Content-Type: application/x-www-form-urlencoded
> Content-Length: 68

| j_username=admin&j_password=admin&remember-me=undefined&submit=Login

Example call from Insomnia REST client:

rest_client_insomnia_step1

Step 2: Calling endpoints

After authentication one can call any endpoint. To start a flow for example:

http://localhost:8080/api/connector/1/flow/start/1

As you can see the REST endpoint are using ID's, instead of the name of the Gateway or Flow. To get the ID of the gateway:

Settings --> Gateway

get_gatewayid

To get the ID of a flow just hover over the edit button on the flow page:

get_flowid

Besides the request url similar headers can be set as when making the authentication call. Difference is that we can now reuse the session cookie (JSESSIONID) and csrf cookie (XSRF-TOKEN).

To set to return type use the "Accept" header. In most cases "application/json" can be used, but for the Connector resource also "application/xml" or "text/plain" can be used.

Example call:

> GET /api/connector/1/flow/start/1 HTTP/1.1
> Host: localhost:8080
> User-Agent: insomnia/6.5.3
> Cookie: JSESSIONID=3UPoreZMv9BHCgGGSiienQjLzLCoQDhoa_4yqVx4; XSRF-TOKEN=936a9190-87f4-444b-9d36-8abf1fc65a7b; remember-me=
> Accept: application/xml
> X-XSRF-TOKEN: 936a9190-87f4-444b-9d36-8abf1fc65a7b
> Content-Type: application/x-www-form-urlencoded
> Content-Length: 0

Example call from Insomnia REST client:

rest_client_insomnia_step2

A succesful result returns:

<response>
  <path>/connector/{connectorId}/flow/start/{id}</path>
  <details>succesful</details>
  <id>1</id>
  <message>started flow 1</message>
  <timestamp>2019-05-23 07:35:43.806</timestamp>
  <status>200</status>
</response>

Besides the response we can check the status with:

/connector/{connectorId}/flow/status/{id}

or just log in the GUI and see if the flow is active.

Clone this wiki locally