Http Request

Http Request makes one HTTPS call to an API outside Slen and puts the answer into the execution. The node is frozen unless the service is set up otherwise: the palette does not offer it, and a new version may not hold it. A version published with it goes on running, and this page says what the node does there.

What it does

The node builds one request from its settings and the values of the execution, makes the call and reads the answer. An answer with a 2xx status leaves through Default. Everything else leaves through Error: another status, a redirect included — the node does not follow one; a request it could not build; an address the service refuses; a host it could not reach; an answer longer than the node may read.

• The address is always https on port 443, and its host is a name on the allowlist of the service — the host itself or a subdomain of it. The allowlist is one for the whole service, and whoever runs the service sets it. With an empty allowlist the node calls nothing.

• Before every call the node checks the host against the allowlist again, and refuses a host whose name leads to an address that is not public. The call goes through no proxy.

• The node spends time, not money: it holds and charges nothing.

When to use it

A new version cannot hold the node, so you meet it in a version published before the node was frozen. A draft that still holds it is not published until the node is taken out — Publish, versions and rollback says how the check reads.

To bring data of another API into a request, call that API from your application, and send what it answered in the input or the context of the request — Send a request.

Settings

• A placeholder is a path in double braces, such as {{input.customer_id}}: the path of the address and its query may hold them, the host may not. The node fills each with the value at the path, encoded for an address. A number is written as it is, and true and false as words. A path that finds nothing, null, a list or an object is not filled: the node makes no call and leaves through Error.

• A path into nodes names a node that runs before this one.

• The node asks for JSON. With a body it sends Content-Type: application/json.

• A header that carries a credential — an authorization, a cookie, an API key — is refused: the flow is stored as plain JSON, and such a header would keep a secret in plain text.

• Unless the service is set up otherwise, the node waits 5 seconds for an answer and at most 15, and reads 65,536 bytes of it and at most 262,144. The connection itself has to be made within 3 seconds.

Ports

The node has two ports. Default is required: a flow in which it leads nowhere is not published. Error is optional. When it leads nowhere and the call fails, the execution ends failed with the code http_request_failed.

Output

The output is the answer: its status, its body when the body is a JSON object or list, its text otherwise.

{ "status": 200, "body": { "tier": "pro" }, "text": null, "error_code": null }

A call that got no answer leaves status empty and says why in error_code:

{ "status": null, "body": null, "text": null, "error_code": "host_not_allowed" }

A later node reads the answer as nodes.<key>.output.body — here nodes.call.output.body.tier, when the key of the node is call. Return Response with the source Output of a node answers with the whole output.

Errors

The node writes one http_called event into the trace for each call. The event names the method, the host, the path as the author wrote it — the placeholders unfilled — the status, the time and the size of the answer. What a placeholder was filled with, the query and the headers are not written. A call that produced no answer carries a reason.

[
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/customers/{{input.customer_id}}", "status": 404, "duration_ms": 182, "bytes": 61, "reason": null } },
  { "type": "http_called", "node_key": "call", "payload": { "method": null, "reason": "url_placeholder_unresolved" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": null, "reason": "body_unresolved" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": null, "reason": "url_unparseable" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/plans", "status": null, "duration_ms": 0, "bytes": 0, "reason": "egress_not_configured" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/plans", "status": null, "duration_ms": 0, "bytes": 0, "reason": "host_not_allowed" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "203.0.113.7", "path": "/v1/plans", "status": null, "duration_ms": 0, "bytes": 0, "reason": "host_is_address_literal" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/plans", "status": null, "duration_ms": 12, "bytes": 0, "reason": "host_unresolvable" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/plans", "status": null, "duration_ms": 9, "bytes": 0, "reason": "address_not_public" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/plans", "status": null, "duration_ms": 5004, "bytes": 0, "reason": "unreachable" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/plans", "status": 200, "duration_ms": 1310, "bytes": 2048, "reason": "request_failed" } },
  { "type": "http_called", "node_key": "call", "payload": { "method": "GET", "host": "api.example.com", "path": "/v1/plans", "status": 200, "duration_ms": 240, "bytes": 65537, "reason": "response_too_large" } }
]

An answer with a status outside 2xx has no reason: the status says what happened.

A draft that holds the node is refused with node_type_frozen — Publish checks. The settings of the node are checked as well, when the flow is validated and when it is published:

Example

The node calls the address of its settings with the customer of the request in the path. Return Response answers with the output of the node. When the call fails, the execution goes to Reject Request and ends rejected with the code the node is set to.

Related

• Execution context and paths — what a placeholder and the path of the body may read.

• Ports and branching — what a port that leads nowhere does.

• How a flow is built — every node of the builder.