Skip to content

HTTP Request – calling an external API

The command "HTTP Request" sends a request to an external HTTP API and writes the answer into variables. This page is for administrators who connect nexxcite with other systems – REST services, webhooks, intranet applications.

1. At a glance
Purpose Send an HTTP request and receive status, headers and body of the answer
Typical use Read data from a REST API; send a record to another system; trigger a webhook
Where in the editor Toolbar menu "Communication" → "HTTP Request"
Needs a user interface No
Related OAuth2 Get Token, OAuth2 User Authorization, AWS Signed Request, Iterate JSON

Summary

  • Method, address, body and headers are expressions, so they can contain values of the record and variables.
  • The answer is text. Values are read out of JSON or XML with value modification rules.
  • Neither an error status nor a connection failure stops the action. Check the status code and the error variables before you trust the body.

Which authentication?

The API expects Use
An API key or a fixed token A request header, for example Authorization with Bearer and the token, or the header name the API documents
NTLM (Windows authentication in the intranet) "NTLM Authentication" on this command (tab "Authentication")
An OAuth2 token for the application OAuth2 Get Token before this command, token in the Authorization header
An OAuth2 token for the signed-in user OAuth2 User Authorization before this command
An AWS signature AWS Signed Request instead of this command

2. Settings

"Display Name", "Description" and "Execution Condition" are on the tab "General" (see Actions).

Tab "Request Settings"

Setting Meaning Default / Required
"Method" Expression for the HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE or CONNECT (case does not matter) Required
"Url" Expression for the absolute address, including the query string Required
"Body" Expression for the request body, as text – for example JSON Empty
"Ignore Certificate Errors" Accepts an invalid TLS certificate of the server Off

Tab "Authentication"

Setting Meaning Default / Required
"NTLM Authentication" Authenticates with NTLM instead of a header Off
"NTLM User Name" Expression for the user name. Empty: the identity of the account the application server runs under. Empty
"NTLM Password" Expression for the password; only read when a user name is set Empty
"NTLM Domain" Expression for the Windows domain. Leave it empty when the user name already contains it (DOMAIN\user or user@domain). Empty

Tab "Request Headers"

The plus button adds a header with "Name" and "Value", both expressions. A header whose name or value is empty is not sent. A header that appears several times is sent with all its values.

Tab "Response"

Setting Meaning Default / Required
"Response Headers Variable" Receives the headers of the answer as a JSON array of objects with name and values Optional
"Response Code Variable" Receives the HTTP status code as a number, for example 200 or 404. 0 after a connection failure. Optional
"Response Body Variable" Receives the body of the answer as text Optional
"Has Error Variable" true when no answer arrived (connection, DNS, TLS, timeout), otherwise false Optional
"Error Variable" The reason of the failure; empty on success Optional

A response that is not written into a variable is discarded.

3. Behaviour

  1. The expressions are evaluated against the current record and the variables.
  2. If the address is empty or the method is not one of the methods listed above, the request is not sent: the command is skipped and the response variables keep their values.
  3. The body is sent with POST, PUT and PATCH; with DELETE and OPTIONS only when it is not empty. GET, HEAD, TRACE and CONNECT never carry a body.
  4. Headers starting with Content- belong to the body and are only sent when a body is sent. Without a Content-Type header the body is sent as text/plain – add Content-Type with application/json when the API expects JSON.
  5. Redirects of the server are followed.
  6. When an answer arrives – whatever its status code – status, headers and body are written, and "Has Error Variable" is set to false.
  7. When no answer arrives, "Response Code Variable" is set to 0, the body to empty, the headers to an empty list, "Has Error Variable" to true and "Error Variable" to the reason. The reason is also written to the log.
  8. The action continues in both cases.

A request that gets no answer is given up after 100 seconds. This time cannot be changed.

NTLM

With "NTLM Authentication" on and no user name, nexxcite authenticates as the account the application server runs under – the usual way to reach an intranet endpoint such as SharePoint or an on-premises Exchange. With a user name, the credentials are offered for NTLM only and only to the address of the request.

4. Examples

Read a customer from a REST API.

  • "Method" GET
  • "Url" https://crm.example.com/api/customers/ followed by the customer number field
  • Header Authorization = Bearer followed by the global value CRM API key
  • "Response Code Variable" Status, "Response Body Variable" CustomerJson

The next command updates the record only when Status is 200 (its "Execution Condition") and reads the name with a Modify Value expression on CustomerJson with the rule JObjectJsonPathValue, path $.name.

Send a record as JSON.

  • "Method" POST, "Url" https://erp.example.com/api/orders
  • "Body": a Modify Value expression that builds the JSON with the rule JObjectSetProperty
  • Header Content-Type = application/json

Process a list from the answer. Iterate JSON over the response body – or over an array inside it – runs commands once per element.

5. Limitations

  • The body is always text. Binary uploads (multipart/form-data, files) are not supported.
  • The answer is read as text. Binary answers (a PDF, an image) do not arrive intact and cannot be stored as files.
  • No retry: a failed request is not repeated automatically.
  • Secrets in headers or in "NTLM Password" are part of the action definition, or of the global value they are read from, and are stored readable. Grant the permissions for actions and global values accordingly (see API access and credentials).
  • "Ignore Certificate Errors" removes the protection against a server that pretends to be another one. Use it only for test systems you control.