HTTP Requests

Overview

The HTTP Requests integration in Automation Gateway allows users to send HTTP Requests to Inventory Devices. This means that you can communicate with any networking device which supports management protocols that have HTTP as a transport option. Examples include REST, RESTCONF, NETCONF, JSON-RPC, gRPC, and many more.

Note: For use cases that Automation Gateway has a direct integration for, such as NETCONF, one should use the specific integration directly to avoid having to deal with the HTTP layer necessarily present in the HTTP Requests integration.

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 in order to avoid unnecessary duplication and promote good practices for the handling of 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 Automation Gateway's general name/variables formatting. A device can be added via API call or by utilizing the GUI.

Via API

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

{
  "name": "...",
  "variables": {
    "protocol": "...",
    "base_url": "..."
  }
}

Via GUI

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

Figure 1: HTTP Request Device

Fill-in the variables. Variables marked with an asterik are required.

Figure 2: HTTP Request Device Variables

Jinja Variables

HTTP Requests allow the user to reference Inventory Device variables inside of a request execution. A common use case would be to supply "username" and "password" variables in the Inventory Device so they do not need to be explicitly supplied in the request call.

{
  "name": "...",
  "variables": {
    "protocol": "...",
    "base_url": "...",
    "username": "username",
    "password": "password"
  }
}

Example Inventory Device

{
  "name": "arista_eos",
  "variables": {
    "protocol": "https",
    "base_url": "arista_eos.local",
    "username": "username",
    "password": "password"
  }
}

Execution

A user who would like to manage a remote device via HTTP can execute a request against an existing Inventory Device via API or by utilizing the GUI. The provided information is then combined with the Inventory Device variables and sent along 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 the use of endpoints from REST calls to gRPC executions. This means, in its current form, that the user must supply variables such as the HTTP request type, headers, data, etc. depending on what type of call they are trying to make and what data the end device expects to be present.

Executing an HTTP Request

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

Via API

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

Due to the diversity of requests, a single general example is difficult to fully display the flexibility of HTTP Requests. However, the most simple request only has a handful of required keys.

{
  "host": "example_host",
  "method": "GET",
  "endpoint": "/status"
}

Via GUI

Users can navigate to HTTP Requests on the sidebar, select the Requests tab, and then the Execute tab.

Figure 3: HTTP Request Execution

Fill-in the variables. Variables marked with an asterik are required.

Figure 4: HTTP Request Execution Example

Ensure the Preview looks as intended.

Figure 5: HTTP Request Execution Example Preview

Jinja Variables

In order to reference a variable from the targeted Inventory Device, you can simply supply Jinja syntax with the variable name. This allows you to keep your secrets, or other information, in a centralized place in Automation Gateway, rather than having to explicitly supply it with every request.

For instance, here is an example request snippet where the username and password are pulled in from a given Inventory Device:

{
  ...,
  "auth": {
      "username": "{{username}}",
      "password": "{{password}}"
  },
  ...
}

Advanced Use Cases

Depending on your comfortability with Jinja, you can supply conditional statements as well as simple dereferencing syntax. As an example, perhaps 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 will allow one request call to work with multiple different usernames regardless of the key or value underneath.

{
  ...,
  "auth": {
      "username": "{{username if username else api_username}}",
      "password": "{{password}}"
  },
  ...
}

Example JSON-RPC Call

{
  "host": "arista_eos",
  "endpoint": "/command-api",
  "method": "POST",
  "auth": {
      "username": "{{username}}",
      "password": "{{password}}"
  },
  "headers": {
    "content-type": "application/json"
  },
  "data": {
    "jsonrpc": "2.0",
    "method": "runCmds",
    "params": {
        "version": 1,
        "cmds": [
            "show clock",
            "show version",
            "show running-config"
        ],
        "format": "json"
    },
    "id": 1
    }
}