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 exposed API calls, you’ll find a sum-up of the general structure of standard Rulex Platform API requests as well as the general response behavior.

Another important topic common to all 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.

Warning

REST API service is exposed only in Rulex Platform Server/Cloud version.

In Standalone version please use the Rulex Platform Command Line Interface.

Using the general approach it is possible to map all these API calls in command line arguments.

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 elements:

  • 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 the following:

Header Name

Description

Authorization (mandatory)

The authentication token, retrieved via the Auth Token call, must be entered in the Authorization header at the beginning of almost all API calls (except the AuthToken, GetFile and the Get Result requests), in the format:
Bearer {your access token}.

Content-Type (optional)

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

  • “application/json“ : (default) 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 (mandatory in the LoginAPI request only)

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 in all the requests except the LoginAPI, where it is required that the user creates and inserts a customized ID, which must be a valid UUID.

X-Rulex-Request-Type (optional)

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“: (default) 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-Request-License (mandatory only if the LoginAPI request has been used in the current session)

A string, in Rulex format, provided by the License Manager. If it is present in API requests, it prevents them from connecting to the license manager when no internet connection is present, or when the server cannot connect to the License Manager due to restrictions.

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, consequently, it is 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 related 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 pages). 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 APIs 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 presents 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 extended version of the error message.

Some API calls may have some extra fields; 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

The authentication is requested through a dedicated API call, which has 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 any API call users need to define a REST API user inside Rulex Platform through GUI. The complete procedure to create this type of user is reported here.

In this example we’ve created a client ID/secret user and have stored its sensitive information for subsequent usage.

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

curl --location --request POST 'your_rulex_cloud_url' --header 'Content-Type: application/x-www-form-urlencoded' --data-raw '{
          "grant_type": "client_credentials",
          "client_id": "<yourclientid>",
          "client_secret": "<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 you gather the access_token entry to be used in the subsequent request.

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

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, supposing it was successful (status 200), the answer will be something close to:

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

License management in REST API

Every time an API request is sent, Rulex Platform backend tries to connect to Rulex License Manager server. If no internet connection is provided, or if the backend server has restrictions towards Rulex License Manager, the client needs to log in and log out manually on the License Manager.

To do so, two API requests are provided:

LoginAPI

This request needs to be sent before or after the Authentication request.

It is required that users create and insert a customized X-Rulex-Request-ID, which must be a valid UUID. More information can be found in the corresponsing section.

This way, users can obtain a temporary connection to the server, and the request returns a string, which is the License Manager session, in a specific format that must be used in each subsequent request’s header called x-rulex-request-license.

POST https://licensemanager.rulex.cloud/license/loginapi

Parameters

Parameters in bold are mandatory

Location

Name

Description

Type

querystring

productkey

The user’s Product Key.

str

querystring

timestamp

The timestamp of the request. Its format must be ISO8601 compliant, so it will be YYYY-MM-DDHH:MM:ss.sssZ. Date and time must be coherent with the UTC date and time.

str

querystring

duration

The duration of the login. If not specified, it is 5 minutes by default. Its format must be an integer followed by min for minutes, h for hours and d for days. E.g.: 30min

str

Response

The response schema for this specific request is:

{
   "x-rulex-request-license": "license_request_in_rulex_format"
   "x-rulex-request-id": "the_id_of_the_response"
}

Warning

To successfully use all the subsequent requests in the current session, fill the other requests’ headers x-rulex-request-license and x-rulex-request-id with the values provided by the LoginAPI request.

Logout

This request must be sent to end the generated session between the client and the License Manager server.

POST https://licensemanager.rulex.cloud/license/logout

Parameters

Parameters in bold are mandatory.

Location

Name

Description

Type

querystring

productkey

The user’s Product Key.

str

querystring

sessionid

The X-Rulex-Request-ID, which has been provided in the response of the LoginAPI request.

str

querystring

timestamp

The timestamp of the request. Its format must be ISO8601 compliant, so it will be YYYY-MM-DDHH:MM:ss.sssZ. Date and time must be coherent with the UTC date and time.

str

Response

The response schema for this specific request is:

{}

Available APIs on Rulex Platform

Here users can find the whole list of exposed REST API calls.