Using Rulex Platform REST API

Here you can browse the full Rulex Platform’s API documentation and find out how to use API requests and how to interpret the responses.

Before jumping into the description of all the exposes API calls we will summarize the general structure of a standard Rulex Platform API requests as well as the general response behavior.

Another important topic which is in common for all the API calls towards Rulex Platform REST API service is the authentication procedure.

Before any API request user must be authenticated against Rulex Platform Authentication Server. The procedure to obtain the authentication token is presented in a dedicated section.

The whole list of all the API methods available on Rulex Platform service is present in a dedicated reference page.

API Structure

API requests are made up of the following:

  • Headers

  • Endpoint

  • Body

Headers

Rulex APIs are case-insensitive. The X-Rulex- prefix indicates custom headers.

Note

Headers are not required by: Auth Token, Get File, Get Result API calls.

The standard headers for requests are as follows:

Header Name

Description

Authentication

The authentication token, retrieved via the Auth Token call, must be entered in the Authentication header at the start of almost all API calls, in the format:
Bearer {your access token}.

Content-Type

The type of contents included in the body. Possible values are:

  • “application/json”: a JSON dictionary of hierarchical objects. The body of a request and response are normally in JSON format.
  • “text/plain”: a plain text file, which usually contains the description of any generated error.
  • “application/octet-stream”: a binary file, returned only by GetFile.

X-Rulex-Request-ID

A 16-character alphanumerical GUID code.
It is customizable, so users can use personal codes to identify the requests, if needed.
If it is not specified, the backend will provide an ID for the current request.

X-Rulex-Request-Type

API requests can be sent in two ways:

  • “sync”: synchronous calls, which wait for request completion, and return a response. If the specified maximum time is exceeded, the call will fail due to timeout.
  • “async”: asynchronous calls, which do not wait for a response, but simply send an acceptance of request response (202 accepted) with an ID of the request.
    To then receive information on the status of the call a Get Result must be sent, with the ID of the call provided in the 202 response.
    The information provided subsequently depends on the type of call.

X-Rulex-Refresh-Token

An alphanumerical code, similar in structure to the authentication token, can be used to renew a token when it has expired. It lasts longer than the access token.

Endpoints

The endpoint is made up of:

  • the method

  • the route URL comprehensive of eventual path and query string parameters

The following is an example of an API post method, which creates a new task in a specific flow. Its description contains a path parameter (the flow identifier flowId) and two query string parameters (name and category).

POST 'https://test.rulex.cloud/api/session/Create/Task/{flowId}?name={name}&category={category}'

The API method can either be:

  • GET – this type of API retrieves information, such as the list of flows

  • POST – the type of API send information to perform an action, such as the creation of a task.

The route URL contains the following route terms:

Name

Description

Example Values

Host

The host is client dependent, and is consequently not usually included in the endpoint in API documentation.

https://test.rulex.cloud

Root

The API is the root of the call, which in this case is always API.

api

Recipient

The recipient is the area of action of the call, which can be:

  • resource – any CRUD calls, involving creation, modification, or deletion.
  • session – calls relative to an active session on a flow or task.
  • compute - calls related to computation.

session

Action

The type of operation performed by the API.

create

Subject

The subject of the operation. For example, if the call changes the name of a flow, Flow will be the subject.

task

Path parameters

Mandatory parameters, which will result in the method failing if not provided.
They are displayed in curly brackets, and each parameter is separated with a backslash.

{rflId}

Query string parameters

Optional parameters, included at the end of the URI, after a question mark (“?”).
They are displayed in curly brackets, and each parameter is separated with a “&”.

?name={name}&category={category}

Body

Not all API requests contain a body:

  • GET API retrieve information, so generally they do not have a body.

  • POST API send information, which is usually included in the body of the request.

Rulex Platform REST API request body is always in JSON format and contains different key/value entries as specified in the reference description of the particular API call (see the reference manual). Still in the reference API manual, you can find the correct type for the value in each entry.

API Response

API responses are made up of the following:

  • Headers

  • Status code

  • Body

Headers

The standard headers for responses are as follows:


Header Name

Description

X-Rulex-Request-Id

A 16-character alphanumerical GUID code. This is always present in responses, and can be used by the Get Result call to retrieve the status of an asynchronous call (within 2 days).

X-Rulex-Response-Timestamp

The response’s timestamp. It is provided in YYYY-MM-DD format, followed by the time (GMT time).

Content-Type

The type of contents included in the body. Possible values are:

  • “application/json”: a JSON dictionary of hierarchical objects. The body of a request and response are normally in JSON format.
  • “text/plain”: a plain text file, which usually contains the description of any generated error.
  • “application/octet-stream”: a binary file, returned only by Get File.

Status code

The main response status codes used in all Rulex API’s are:

  • 200 - success

  • 202 - accepted

  • 230 - warning

  • 500 – error

  • 400 - bad request

For other codes not listed here see Microsoft Documentation

Body

The response body of any API call is in JSON format by default and present the following entry:

  • code: containing the internal error code in case of error or 0 in case of success.

  • data: the real result of your execution and its form differs for any API call.

  • desc: in case of error this entry contains the error message in a verbose fashion.

Some API call may have some extra field; in this case their structure is specified in their API description.

API Authentication

All Rulex APIs require an authentication token, which can be obtained through two different types of authentication:

  • Client ID & Secret

  • Signed JWT (JSON Web Token)

The authentication is requested through a dedicated API call, which a specific structure

POST /api/auth/token

The call does not require any headers, and its parameters depend on the type of authentication selected.

Note

For details on the auth/token call see the Auth Token requests’ page.

Sample API call

First, to perform we need to define a REST API user inside Rulex Platform through GUI. The complete procedure to create such a user is reported here.

For this example we had created a client ID/secret user and to have stored this sensitive information for subsequent usage.

The preliminary authentication call to obtain the user token is as following:

curl --location --request POST 'your_rulex_cloud_url' --header 'Content-Type: application/json' --data-raw '{
          "auth_type": "client-secret",
          "clientId": "<yourClientId>",
          "clientSecret": "<yourClientSecret>"
      }'

The answer of this call is something similar to:

{
   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmSUd5bXBKSE1PWjhZb3N2YzN4QTV4Q25lV3ZENmdNbzF4VlkyYzR5dGRRIn0.eyJleHAiOjE2ODk2ODQ3MTcsImlhdCI6MTY4OTY4NDExNywianRpIjoiNTUyNjBhNGEtZDI0NC00ZGRkLTlmZWQtODM5ZGFiMTE3YzFhIiwiaXNzIjoiaHR0cHM6Ly90ZXN0LnJ1bGV4LmNsb3VkL2F1dGgvcmVhbG1zL3J1bGV4IiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImY0OWNlYjY2LWI5MzAtNGNiMy1iNGQyLWMzZWRjMGE3YzAwMSIsInR5cCI6IkJlYXJlciIsImF6cCI6InNlcnZpY2VwcmluY2lwYWxfMV9yZXN0YXBpIiwic2Vzc2lvbl9zdGF0ZSI6IjVkMDE4MGFkLWZiMTItNGQ5Mi1iZWI2LTUyOGY5MzI4NTBkYSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsImRlZmF1bHQtcm9sZXMtcnVsZXgiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsInNpZCI6IjVkMDE4MGFkLWZiMTItNGQ5Mi1iZWI2LTUyOGY5MzI4NTBkYSIsImNsaWVudEhvc3QiOiIxMC4xLjY0LjEzMyIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SWQiOiJzZXJ2aWNlcHJpbmNpcGFsXzFfcmVzdGFwaSIsImdyb3VwcyI6WyJvZmZsaW5lX2FjY2VzcyIsImRlZmF1bHQtcm9sZXMtcnVsZXgiLCJ1bWFfYXV0aG9yaXphdGlvbiJdLCJzZXJ2aWNlX2dyb3VwcyI6WyJNeUdyb3VwIl0sInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1zZXJ2aWNlcHJpbmNpcGFsXzFfcmVzdGFwaSIsInByb2R1Y3RrZXkiOiJESUY0Mi1VR1lQWS1CUFMxUy1SQUdLVS1JUU9DQyIsImNsaWVudEFkZHJlc3MiOiIxMC4xLjY0LjEzMyJ9.p3oxj4GS4EMdvLJGnrKv92evlgPn7giP41DiNkR9e21MBG3r6khFqqIapNcs85Pc2k2E90zEhE891IYyVVXhUSjw4N23TJhgNfDJKLJvEiwSPrCTLfMSxfu4j3PG9G-JudnQ0omxZxtZ49Isi954E2YNU3VujXDnQbIw8KPC1hxFsv9A33G6En9edM-OezavYPPYCpLgWXFHXMXl3UKviEO1tp6usGlM78e7JKoTwpFykw1Sr5DjrromB3rc4WJqPFmJWAm3O5UJKymeHR3fvAlmcxKwE1XuZvgz7rizBJU6eUa-M0I_w3kXd10K5H9YZ05Tl_OjKZvdaRq5pLJSng",
   "expires_in": 600,
   "refresh_expires_in": 1800,
   "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3ZmM3OGZlYS1lM2E1LTQyN2UtODE4MS1kYzAxMjk5OTIxMGMifQ.eyJleHAiOjE2ODk2ODU5MTcsImlhdCI6MTY4OTY4NDExNywianRpIjoiMDJiZTUzNzYtNjFlZC00ZGRlLThhNTMtYzE3YWZmMTI5ODYyIiwiaXNzIjoiaHR0cHM6Ly90ZXN0LnJ1bGV4LmNsb3VkL2F1dGgvcmVhbG1zL3J1bGV4IiwiYXVkIjoiaHR0cHM6Ly90ZXN0LnJ1bGV4LmNsb3VkL2F1dGgvcmVhbG1zL3J1bGV4Iiwic3ViIjoiZjQ5Y2ViNjYtYjkzMC00Y2IzLWI0ZDItYzNlZGMwYTdjMDAxIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InNlcnZpY2VwcmluY2lwYWxfMV9yZXN0YXBpIiwic2Vzc2lvbl9zdGF0ZSI6IjVkMDE4MGFkLWZiMTItNGQ5Mi1iZWI2LTUyOGY5MzI4NTBkYSIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsInNpZCI6IjVkMDE4MGFkLWZiMTItNGQ5Mi1iZWI2LTUyOGY5MzI4NTBkYSJ9.19YVFaiW82PIPOa8ZFaT-sV-_7ARuKeEIhCJaYy6Elk",
   "token_type": "Bearer",
   "not-before-policy": 0,
   "session_state": "5d0180ad-fb12-4d92-beb6-528f932850da",
   "scope": "profile email"
}

From this answer we gather the access_token entry to be used in the following request.

In this sample we are going to produce in cURL, a synchronous API call to compute in full computation a whole Rulex Factory Flow:

curl --location --request POST 'https://' \
--header 'Authorization: Bearer <yourAccessToken>' \
--header 'Content-Type: application/json' \
--header 'X-Rulex-Request-Type: sync' \
--data-raw '{}'

At the end of the computation, which we suppose to be successful (status 200), the answer will be something similar to:

{
   "status": "completed",
   "progress": "100%",
   "code": 0,
   "data": {},
   "desc": ""
}