HTTP requests

Overview

The HTTP Requests integration in Itential Automation Gateway (IAG) allows you to send HTTP requests to inventory devices. This means that you can communicate with any networking device that supports management protocols with HTTP as a transport option. Examples include REST, RESTCONF, NETCONF, JSON-RPC, gRPC, and many more.

Inventory

The main purpose of an inventory device, in terms of HTTP Requests, is to supply the protocol (http/https) and base_url (domain name/IP address) information for requests so that it can build the URL for the request, regardless of a specific request endpoint. Additionally, variables may be stored here and referenced in the request to avoid unnecessary duplication and promote good practices for handling sensitive variables such as credentials or other secrets. See the Jinja categories for additional information on variable references.

Inventory device creation

Inventory device creation follows IAG’s general name/variables formatting. A device can be added via API call or by using the GUI.

Via API

For detailed information about this piece of the API spec, see the Swagger endpoint: /api/v2.0/inventories/http_requests.

1
{
2
  "name": "...",
3
  "variables": {
4
    "protocol": "...",
5
    "base_url": "..."
6
  }
7
}

Via GUI

1

Open the Create dialog

Select the + button in the left sidebar to open the Create dialog, then select the HTTP Request Device option.

2

Fill in the variables

Fill in the variables. Variables marked with an asterisk are required.

Jinja variables

HTTP Requests allow you to reference inventory device variables inside a request execution. A common use case is to supply username and password variables in the inventory device so they do not need to be explicitly supplied in the request call.

1
{
2
  "name": "...",
3
  "variables": {
4
    "protocol": "...",
5
    "base_url": "...",
6
    "username": "username",
7
    "password": "password"
8
  }
9
}

Example inventory device

1
{
2
  "name": "arista_eos",
3
  "variables": {
4
    "protocol": "https",
5
    "base_url": "arista_eos.local",
6
    "username": "username",
7
    "password": "password"
8
  }
9
}

Execution

You can execute a request against an existing inventory device via API or by using the GUI to manage a remote device via HTTP. The provided information is then combined with the inventory device variables and sent to the end device. Because there are several different protocols and implementations based on HTTP, this integration aims to be as generic as possible to enable use of endpoints from REST calls to gRPC executions. In its current form, you must supply variables such as the HTTP request type, headers, data, and so on, depending on the type of call you are trying to make and what data the end device expects.

Execute an HTTP request

A request can be executed via API call or by using the GUI.

Via API

For detailed information about this piece of the API spec, see the Swagger endpoint: /api/v2.0/http_requests/request/execute.

Due to the diversity of requests, a single general example cannot fully display the flexibility of HTTP Requests. However, the simplest request requires only a handful of required keys.

1
{
2
  "host": "example_host",
3
  "method": "GET",
4
  "endpoint": "/status"
5
}

Via GUI

1

Navigate to the Execute tab

Navigate to HTTP Requests in the sidebar, select the Requests tab, then select the Execute tab.

2

Fill in the variables

Fill in the variables. Variables marked with an asterisk are required.

3

Verify the preview

Ensure the Preview looks as intended.

Jinja variables

To reference a variable from the targeted inventory device, supply Jinja syntax with the variable name. This allows you to keep your secrets or other information in a centralized place in IAG, rather than explicitly supplying it with every request.

The following example request snippet pulls the username and password from a given inventory device:

1
{
2
  ...,
3
  "auth": {
4
      "username": "{{username}}",
5
      "password": "{{password}}"
6
  },
7
  ...
8
}

Advanced use cases

Depending on your familiarity with Jinja, you can supply conditional statements as well as simple dereferencing syntax. For example, if some of your hosts use the username variable name and others use api_username, you can write a simple if statement to try to grab the first but default to the second. This allows one request call to work with multiple different usernames regardless of the key or value.

1
{
2
  ...,
3
  "auth": {
4
      "username": "{{username if username else api_username}}",
5
      "password": "{{password}}"
6
  },
7
  ...
8
}

Example JSON-RPC call

1
{
2
  "host": "arista_eos",
3
  "endpoint": "/command-api",
4
  "method": "POST",
5
  "auth": {
6
      "username": "{{username}}",
7
      "password": "{{password}}"
8
  },
9
  "headers": {
10
    "content-type": "application/json"
11
  },
12
  "data": {
13
    "jsonrpc": "2.0",
14
    "method": "runCmds",
15
    "params": {
16
        "version": 1,
17
        "cmds": [
18
            "show clock",
19
            "show version",
20
            "show running-config"
21
        ],
22
        "format": "json"
23
    },
24
    "id": 1
25
    }
26
}