API Request

In this tutorial you will learn about the API Request Node, what it does and how to use and its Settings

1. What it does

Sends a HTTP API requests and returns the response.

2. How to use

Place this node where ever you need to get/send some data from an API.

Example: When user asks for some jokes, we get a Chuk Norris Jokes, from an API https://api.chucknorris.io/jokes/random
The response of the API request would be poplute in msg.payload object, here we have selected the Return value as a parsed JSON object, so msg.payload would be a JSON object.
In order to extract and send chuck norris joke to the user, we need to place the Message Node, with content as {{msg.payload.value}}.

If your API url varies, you can also provide your url in some msg object’s property like msg.url.
Example: If you set,
msg.url = “https://api.chucknorris.io/jokes/random"
then you can use this variable inside the URL Node settings like below
{{{msg.url}}}
Note: Make sure to enclose the msg.url triple enclosed curly braces. Only use alphabetics, . and _ when referencing. Do not use white spaces, or any other special character.

To Send some data with the HTTP API:

For Method as GET, add the data as url query string in URL property
Example: Set URL as
https://api.chucknorris.io/jokes/random?category=political"
For Method as POST, PUT or DELETE, add the data as key/value pair in msg.payload of incoming msg object.
msg.payload = {
  “category” : “political”
}

3. Node Setting

  • Name
    Name for Node
  • Method
    Defined the Method for the Request, default is GET.
    But can also be PUT, POST, PATCH or DELETE.
    Note: If you want to provide the Method manually, then Select the Method as
    - set by msg.method -
    and pass/provide the modified msg object into this Node, which has below details:
      msg.method = “GET”
      msg.method = “POST”             // OR
      msg.method = “PUT”              // OR
      msg.method = “DELETE”           // OR
    
  • URL
    Defines the HTTP API to get the response.
    Instead of adding simple API string, you can also provide msg object propery which contains the URL.
    msg.url = “https://example.com/api/something"
    Note: always use {{{ }}}, when referencing a msg object inside the URL.
    {{{msg.url}}}
    Only use alphabetics, . and _ when referencing. Do not use white spaces, or any other special character.
  • Use basic authentication
    Tick/Check this settings, when your HTTP API need some authentication with HTTP API.
    Right now basic authentication is supported, which include UserName and Password.
  • Return
    The format of response which you want to get from HTTP API. The response of HTTP API is setted in msg.payload propery of outgoing msg object.
    • a UTF-8 String
      Format the response in form of String.
    • a binary buffer
      Format the response into Buffer.
    • a JSON parsed object
      Format the response in form of JSON.
  • Payload
    Sent as the body of the request.
    To Send some data with the HTTP API:

    When Method used as GET, add the data as url query string in URL property
    Example: Set URL as
    https://api.chucknorris.io/jokes/random?category=political"
    When Method used as POST, PUT or DELETE, add the data as key/value pair in msg.payload of incoming msg object.
    msg.payload = {
      “category” : “political”
    }
    

4. Input

API Request Node takes input from from any node.

5. Output

API Request Node modifies the msg.payload, or msg.statusCode or msg.headers depending upon the response from the HTTP API and passes the msg object to next connected node.

Example:

msg = {
    …
    “payload” : (string, object or buffer depending upon the RETURN node setting),
    “statusCode”: (sumber) ,
    “responseUrl”: (string) ,
    …
};

Details:

Details

When configured within the node, the URL property can contain mustache-style tags. These allow the url to be constructed using values of the incoming message. For example, if the url is set to example.com/{{{msg.topic}}}, it will have the value of msg.topic automatically inserted. Using {{{…}}} prevents mustache from escaping characters like / & etc.

Using multiple HTTP Request nodes

In order to use more than one of these nodes in the same flow, care must be taken with the msg.headers property. The first node will set this property with the response headers. The next node will then use those headers for its request - this is not usually the right thing to do. If msg.headers property is left unchanged between nodes, it will be ignored by the second node. To set custom headers, msg.headers should first be deleted or reset to an empty object: {}.