-
-
Notifications
You must be signed in to change notification settings - Fork 9
REST Clients
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.
- Swagger (online)
- cURL (command line)
- Postman (app)
- Insomnia (app)
- Hoppscotch (webapp)
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/
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.
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 -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>'
curl -X 'GET' \
'http://localhost:8088/api/integration/1/flow/start/1' \
-H 'accept: application/xml'
-
Create a new endpoint.
-
Set the http method to "POST"
-
Set the url to: http://localhost:8080/api/integration/1/setflowconfiguration/1
-
Create two headers:
accept: application/xml' 'Content-Type: application/xml'
-
Add the XML to the body:
<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
-
Create a new endpoint.
-
Set the http method to "GET"
-
Set the url to: http://localhost:8080/api/integration/1/flow/start/1
-
Create two headers:
accept: application/xml' 'Content-Type: application/xml'
-
Send
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
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
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
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.
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.
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:
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
To get the ID of a flow just hover over the edit button on the flow page:
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:
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.