REST API - More than a Snooze!

As a Sales Engineer and Solutions Architect, I have a lot of interaction with different ITRS clients, and see a lot of different ways in which they use Geneos. Recently, I was discussing the REST API with a client and was told: “You know, it’s too bad it only runs snooze commands, there are a lot of other things I’d like to trigger remotely.”

“You know, it’s too bad it only runs snooze commands...“

I was baffled, as I was sure it could run any command on the Gateway. What was I basing that on? Had I tested it recently and forgotten? I vowed to myself to go and test it out, and here are getting started notes and takeaways for others working with the Geneos Gateway Command REST API.

The rest APIdoes indeed accept and run other commands.

As outlined below, I’ve tested it with several of the internal gateway commands such as show Rules, and even with a custom bespoke command I configured on the gateway. This means the REST API can be used to remotely trigger remediation actions – even customized ones – at whim, and automatically. 

My test scenarios: 

• /rest/commands/all - Tests baseline API connectivity, details all commands.
• Showrules on a cell - To test internal gateway commands    
• Custom command - Run a user-defined command ‘testCommand’ on cell.

Authentication: 

In my testing, to get started quickly, I didn’t have authentication on the Gateway, so I didn’t have to provide auth info as part of the request, and I could run against the insecure Gateway port. I could just run a plain GET request against my Gateway at http://nysupsvr1f:54100/rest/commands/all 

Start in a no-auth scenario, then once you have a baseline working, enable authentication on the Gateway and add the appropriate changes in the HTTP request. I will address authentication in a subsequent post. 

Tools: 

I used a couple tools to make working with the REST API a little easier. Postman is useful for easily triggering posts in a nice interface, and JSONLint is really useful for checking JSON syntax.

• Postman – everything you could want to do with HTTP requests  https://www.getpostman.com/
• JSONLint – for validating JSON objects. https://jsonlint.com/

Scenario 1: Show All Commands

This is an important tool to note, the REST API has a function one can query to see all the commands available on the Gateway, and to see what sorts of input they expect. 

The target URL for this function is [gateway-rest-api-location]/rest/commands/all 

Due to the size of the result, I’m not including the full response here, it’s a rather large list that quite usefully specifies every command and what arguments it takes. I strongly encourage getting this working first, as it provides a useful reference for subsequent API calls.

You can easily see it’s a large JSON response including command definitions, with fields such as name, but also useful ones like targets (where that command can be used) and arguments (what information that command takes to run). 

The first command listed is an internal command /SNOOZE:manualAllME (manually snooze on all managed entities). After that one is a large chunk of snooze commands, which I have collapsed in the bracket. After all the snooze commands is a user-assignment command (again an internal gateway command).

Scenario 2: Internal Gateway Command - showRules

I’ve included this example as it showcases using an internal Gateway command, but also because it is an example of how an internal Gateway command occasionally requires bizarre arguments. 

For actually running commands, the URL target is different than in the ‘list all commands’ example. So here, the post request was sent to http://nysupsvr1f:54100/rest/runCommand

In this case, rather than a plain GET, we’re actually POST-ing some data with the request. The body of the post is application/JSON.

My first try at running this I was receiving an error message:

"stderr": "Unable to evaluate XPath specified in argument 1"

Normally, I’d expect this to be because the XPATH wasn’t escaped properly, but that actually yields a different error message about invalid JSON request.

I thought to look at the definition of the showRules command in the command list retrieved in test 1.

Looking at the show Rules definition:

We see that showRules does take one argument, so I changed the JSON request to try again with the argument added on.

Revised JSON:

{
  "command": "/RULES:showRules",
  "target": "/geneos/gateway[(@name=\"gabrielTestGateway\")]/directory/probe[(@name=\"GabrielTestProbe\")]/managedEntity[(@name=\"app2ME\")]/sampler[(@name=\"Tester\")]/dataview[(@name=\"Tester\")]/rows/row[(@name=\"row1\")]/cell[(@column=\"col1\")]",
  "args": {
    "1": "/geneos/client/features/@RuleShowEx"
  }
}

And then we get back a success response, with info about the rule, although the format of the rule is somewhat illegible as it’s intended for the Gateway. One is probably better off in GSE – another one of its under sung selling points.

Scenario 3: Custom Command

One big piece of functionality with the REST API that is very desirable amongst our clients is the capability to trigger custom commands, allowing more configurability of integrations as bespoke commands (running whatever process desired), can now be triggered remotely. 

Below is a walk through of using the REST API to trigger a custom command, with screenshots, configuration, and a sample POST – which is pretty similar to the prior requests. 

The first thing I did was open the GSE and edit the gateway config to create a new, custom, command. I just created a simple test one, that just echoes back some data, but as is well known to adept Geneos users, these commands can do anything. My test command:

I ran it once in the Active Console just to make sure it works and verify the functionality:

Then I went about trying to trigger it via the API. 

Because this is not an internal gateway command, the command name is slightly different. For non-internal and custom commands, you just pass the exact name of the command as you built it, no “/FOO:barBaring” naming is needed.

My JSON: 

{
  "command": "testCommand",
  "target": "/geneos/gateway[(@name=\"gabrielTestGateway\")]/directory/probe[(@name=\"GabrielTestProbe\")]/managedEntity[(@name=\"app2ME\")]/sampler[(@name=\"Tester\")]/dataview[(@name=\"Tester\")]/rows/row[(@name=\"row1\")]/cell[(@column=\"col1\")]"
}

As a prep step, I looked for my new command in the ‘get all commands’ list from test 1. Low and behold it is listed. The ‘type’ field says “User” for this one, as opposed to the ‘type’: “Internal” listed for the various gateway internal commands like all the SNOOZE:**** commands.

In this scenario, my test command doesn’t take any arguments due to its design, but you could build one that does, and send them along as was outlined in scenario 2.

We see the request was well formatted and successful, and the response indicates a status of finished. Further, the output returned by the command (normally sent to the output window in Active Console), is also sent back in the JSON response. 

As is the case with commands in the active console, this output field is a useful way of sending some additional returned data, in addition to running the command itself. For example, a command that creates a ticket in a ticketing system might return the ticket number generated, in addition to the success indication ‘status:finished’. 

Another scenario, a bit more pertinent to this API perspective, might be to programmatically return a (small) piece of the gateway logs by triggering a command configured to do so. Substantial outbound data needs should of course use gateway outbound data API options such as Gateway Publishing.  

The REST API is a very flexible and powerful interface, capable of running snooze commands naturally, but also running any gateway command. These could be internal commands (the out-of-the-box commands in Geneos we’re used to using), or custom user-defined commands. Further the response includes the output of the commands, so commands can return data as well as take actions, providing rich status and success information.

To read more about the REST API, see the documentation here: Gateway Commands (REST Service)