SolarWinds API, Part I
This is the first post in a series I’ll be writing about using the REST API to get information out of SolarWinds (and make changes!). We’ll start with a basic query and go from there.
Enter: Postman
Before we write a single line of code we need to make sure that what we’re sending SolarWinds and what we’re getting back makes sense. To do this, there’s an excellent free cross-platform utility called Postman from Postdot Technologies, Inc. that you can download right on their main page for the OS of your choosing.
Authentication
First thing, we need to create a user that’ll give us access to SolarWinds’ API. This is no different than a regular user, but it’s a good idea since you can limit the user’s access to just the minimum that you need without giving it carte blanche to your entire system (as it would have if you used your own credentials).
Permissions
The only permission you need to pull information out of SolarWinds is an active account, but to manipulate it at all (including custom properties) you’re going to need “node management” rights. When you’re just starting with this, start without the node management rights so you don’t do anything you’ll regret.
Basic Query
Now that we have an account we’ll want to fire up Postman and do the API equivalent of our “hello world” tire-kicking query. We’ll ask it for the captions and IP addresses of all of the nodes in our inventory.
There is great information on SolarWinds’ github account in the form of a wiki that you can look over but it only has one example per type of request so it could use more meat (something I’ve got in my list of things to do) but it’s something to get us started. The example they give for a basic query follows:
GET https://localhost:17778/SolarWinds/InformationService/v3/Json/Query?query=SELECT+Uri+FROM+Orion.Pollers+ORDER+BY+PollerID+WITH+ROWS+1+TO+3+WITH+TOTALROWS HTTP/1.1Authorization: Basic YWRtaW46User-Agent: curl/7.20.0 (i386-pc-win32) libcurl/7.20.0 OpenSSL/0.9.8l zlib/1.2.3Host: localhost:17778Accept: */*Let’s unpack that a bit. These lines tell us a few important things:
- We’re going to use GET as our method for requesting basic information from the API in the form of a SolarWinds Query Language (SWQL) query.
- We’re going to use basic authentication (username & password).
- The API lives on port 17778, uses HTTPS, and requires the /SolarWinds/InformationService/v3/Json/ portion be tacked onto the end of the host:port before we even get into what we’re asking it to do (query).
To start we’ll get at least this much information into our new Postman query. When you start it you should start out with a new tab with no information. Populate it with the URL (using your IP address, of course), and then choose ‘Basic Auth’ from the drop down that currently is currently set to ‘No Auth’:
Fill in the dialog with the authentication details for your new SolarWinds user. I named mine ‘automation’. When you’re done, click the “Update Request” button.
Once you’ve done that you should see that the headers for request has been updated and should have a little “(1)” next to it. Click it to see what was added.
That’s the base64-encoded version of your username:password pair. Make sure you don’t share that with anyone because it’s simple to convert this back to plain text. Yes, this means your username and password is going over the wire but that’s why we use HTTPS. Also, you really should only be having these conversations inside your own network.
Now let’s add the actual query. Based on the example above, we need to provide a “query” parameters with the value set to the query that we want to run. To do that, click the “Params” button to expand the parameters interface.
In the key, put ‘query’ and in the value box, put the following:
SELECT Caption, IPAddress FROM Orion.Nodes WHERE Vendor = 'Cisco'Case doesn’t matter for the SWQL query (or the value in the WHERE clause either, for that matter) but I’ve typed it this way for maximum clarity. Make sure you tab out of the value and description boxes so it saves it.
You have something that looks like the following when you’re done. You can see that the URL was automatically adjusted to include a “?” mark to start the query string portion which is made up of our key (query) and value (the actual query above).
Once this is done, you should be able to click the big blue “Send” button on the right-hand side. If everything went well, you should see results like the ones below:
A couple things to notice here. First, the result has its own headers section that you can click on to see what information came along with the result (content length, content type, date, and server type). Second, the formatter being used to display the results is JSON of course because that’s what we asked for in the query (see the /json/ portion above).
Parameterization
Doing a query like this is all well and good, but what if you need to be able to parameters to the query itself? Instead of putting ‘Cisco’ in there, we’ll change that out for a placeholder called ‘@vendor’ that we’ll be able to provide different values for with each request. This will require us to step it up from a GET request to a POST so we have more wiggle room.
Use Ctrl+T or File > New Tab to get a new tab started. To save time, copy the query URL below to the new tab and set the request type to POST:
Change your authorization from “No Auth” to “Basic Auth” – your user from the last exercise should already be there. Click “Update Request” to add that authorization header to your new request.
Now we have to write our request. Let’s see what they say about doing this on the SolarWinds wiki:
POST https://localhost:17778/SolarWinds/InformationService/v3/Json/Query HTTP/1.1Authorization: Basic YWRtaW46User-Agent: curl/7.20.0 (i386-pc-win32) libcurl/7.20.0 OpenSSL/0.9.8l zlib/1.2.3Host: localhost:17778Accept: */*Content-Type: application/jsonContent-Length: 130 {"query":"SELECT Uri FROM Orion.Pollers WHERE PollerID=@p ORDER BY PollerID WITH ROWS 1 TO 3 WITH TOTALROWS","parameters":{"p":9}}Alright, it’s the same information we were working with previously with a few exceptions:
- The request method has been changed from GET to POST.
- There is now an additional “Content-Type” header that describes what format our request will be in (application/json).
- The query is no longer on the first line in a query string but rather has been moved down into the body of the request.
- There are two parts to the body: the query itself, and the parameters that will be used to replace any @parameter entries in the query string.
To do this in Postman, we’re going to have to click over to Body (next to the Authorization and Headers buttons we’ve already used), change the type to “raw” and change the content type to JSON:
Then we’ll put our request in the box just like the example only with the query and parameter values that we care about:
{"query":"SELECT Caption, IPAddress FROM Orion.Nodes WHERE Vendor = @vendor","parameters":{"vendor":"Cisco"}}It should look like this when you’re done:
I’ve written it all on one line, but you could certainly space it out so it’s a little easier to read. As long as it’s valid JSON (you’ll see a little red checkbox if it isn’t) it’s fair game:
{ "query":"SELECT Caption, IPAddress FROM Orion.Nodes WHERE Vendor = @vendor", "parameters":{ "vendor":"Cisco" }}Click the “Send” button and you should see the same results as last time, only with our new and improved parameterized query.
Up Next Time
That’s it for this one. Next we’ll talk about how to make some minor changes to your SolarWinds environment including managing/unmanaging devices, adjusting custom properties, adding nodes, assigning templates, and whatever else comes up. If you have a request, please feel free to shoot me an email at sklassen@loop1.com!
Steven Klassen
Field Systems Engineer
