Skip to main content

REST services

A REST service (RestService) defines a connection to an external HTTP API, with one or more operations a rule can call. REST services are created and edited in the Data section; a rule calls an operation using the Execute REST Operation action.

Create a REST service​

  1. In the Data section, open the ellipsis menu (...).

  2. Select Add REST Service.

    Screenshot of the Data ellipsis menu with Add REST Service highlighted

  3. Enter a name for the service.

    Screenshot of a new REST service with its name field in edit mode, showing the note "Root URL and authentication are configured in environment settings"

note

Root URL and authentication are configured in environment settings. An admin sets these as a tenant override in the Portal, keyed by the service's name, not in the rule application itself.

If a rule application was authored in irAuthor Desktop and already carries REST credentials, those values stay in the rule application's own XML and round-trip through the catalog on check-in. Web authoring doesn't store or display them. To run that rule application in a different tenant, set the tenant override there as well.

note

Operations are authored by hand. Importing a Swagger or OpenAPI definition isn't supported, and a response doesn't have a typed schema (matching Desktop's current REST service support).

Add an operation​

Each operation on a REST service defines one HTTP call.

  1. Open the REST service and add an operation. Define its operation inputs (the values a rule will supply when it calls this operation).

  2. Set the request verb (GET, POST, PUT, or DELETE) and the URI template. Reference an operation input in the URI template with $InputName$ syntax. For example: /members/$memberId$.

  3. Add any headers the request needs. Headers are chosen from a fixed list of standard names (Accept, Accept-Encoding, Accept-Language, Authorization, Cache-Control, Content-Type, Cookie, User-Agent, X-Correlation-Id, X-Request-Id) rather than entered as free text.

    Screenshot of the Headers Name drop-down showing the fixed list of ten standard header names

  4. For a verb like POST that sends a body, choose a body format (XML, JSON, or Form encoded), then write the body. An operation input is referenced in the body the same way as in the URI template ($InputName$).

    Screenshot of a POST operation with Body format set to JSON and a body referencing $memberId$, with the hint text "$token$ resolves against Operation inputs"

Mistakes are caught as you type. For example, referencing an input in the URI template that the operation doesn't define produces an error naming the problem directly.

Screenshot of a live validation error reading "The URI template uses '$planId$', which is not an input on this operation."

Operation settings​

Each operation has its own settings, opened from its gear icon:

Screenshot of the operation Settings panel showing all six settings: Wait for response, Validate status code, Valid status codes, Number of retries, Timeout, and Cache duration

Wait for response
Whether the action waits for a reply before continuing.

Validate status code
Whether a reply's status code is checked against the valid codes below.

Valid status codes
Which status codes count as a success.

Number of retries
How many times to retry the call if it fails.

Timeout (seconds)
How long to wait for a reply before giving up.

Cache duration (seconds)
How long to reuse a previous reply instead of calling again.

Calling a REST service from a rule​

See Execute REST Operation.

note

Deleting a REST service that an operation still uses is allowed. Any rule that calls one of that service's operations reports that the service is missing.

Overriding a REST service for a test run​

When testing, you can override a REST service's connection for that test run only, without changing the rule application or the environment's configuration:

  1. Open the Tester and select Settings.

  2. Under Runtime overrides, select Add override and pick the REST service.

    Screenshot of an empty Runtime overrides panel, reading "Test-run override. An empty field falls back to the tenant configuration."

  3. Override the Root URL, if needed.

  4. Override the Authentication type: Use tenant configuration, None, Basic, NTLM, Kerberos, or Custom. Choosing Basic reveals Username and Password fields.

    Screenshot of a Runtime override with Root URL filled in and the Authentication type drop-down open, showing all six options

  5. Expand Certificates to override the certificate path, certificate password, or to allow untrusted certificates.

    Screenshot of Basic authentication selected with Username and Password fields, and Certificates expanded showing Certificate path, Certificate password, and Allow untrusted certificates

  6. Select Save.

note

A runtime override lasts for the current session only. Closing the Tester without saving discards it; nothing is written to the tenant configuration.