API Structure

API requests are made up of the following:

Headers

Rulex API headers are case insensitive. The “X-” prefix indicates a custom header.

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

The standard headers for requests are as follows:

Header Name

Description

Authorization

The authentication token, retrieved via the Auth API, must be entered in the Authorization header at the start of almost all API calls, in the format: Bearer <your access token>.
See API Authentication for details on how to obtain an authentication 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.

Endpoint

The endpoint is made up of:

  • the method

  • the URI.

The following is an example of an API post method, which creates a new task in a specific flow:

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

Method

The API method can either be:

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

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

URI

The URI contains the following:

Name

Description

Example Values

Host

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

https://your_rulex_cloud_url

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

These are 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

These are 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}

Query 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

Sample request

The following is a sample in cURL of a synchronous API call to export a Rulex Flow:

## Export Flow

Example with cURL:
```
curl --location --request POST 'https://your_rulex_cloud_url' \
--header 'Authorization: Bearer <yourAccessToken>' \
--header 'Content-Type: application/json' \
--header 'X-Rulex-Request-Type: sync' \
--data-raw '{
    "params": {
        "source": {
            "uri": "local"
        }
    }
}'
```

Search