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.

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 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 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 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). 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 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 call 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 we need to define a REST API user inside Rulex Platform through GUI. The complete procedure to create such user is reported here.

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

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

curl --location --request POST 'your_rulex_cloud_url' --header 'Content-Type: application/json' --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 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 it was successful (status 200), the answer will be something similar 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:

{
   Logout successful for username=None machine=None productkey=your_product_key sessionid=your_session_id
   timestamp=2024-06-04T08: 53: 53.026Z host='licensemanager.rulex.cloud'
   x_request_id='request_id' x_real_ip='ip_address' x_forwarded_for='' x_forwarded_host='licensemanager.rulex.cloud'
   x_forwarded_port='port' x_forwarded_proto='https' x_forwarded_scheme='https' x_scheme='https' content_length='0'
   user_agent='agent' accept='*/*' postman_token='postman_token' accept_encoding=' ' x_rulex_platform_version='Rulex_platform_version'
}