Industry consumers are rapidly demanding automation, orchestration and programmability features from vendors, with the goal of making networks and systems more fluid, easy to deploy, and intelligent. Sometimes overlooked, a key component in automation is monitoring and documentation. Sure, you can auto-provision virtual machines and virtual networks, automate branch office connectivity, device policies, and more, but what about your Network Management Software? Nearly all vendors are offering, or starting to offer, APIs and SDKs to accomplish this goal, placing the control in the hands of the user. SolarWinds understand that the future is now, and now requires openness, empowerment and accessibility. Over the past several years, SolarWinds has developed an SDK in an effort to deliver such a goal.
This is the first of several articles in a series we’re calling SolarWinds Orion API & SDK. Before we dive blindly and head-first into this tasty TLA soup, it’s best to cover some basics. In this article we’ll be briefly discussing general concepts like APIs, REST and JSON. Nothing too in depth, just enough to stimulate sedentary neurons in your cranial membrane.
After that, we’ll show you where you can get the SDK and start your SolarWinds DevOps journey. You ready?!
What is SolarWinds API?
What is an API?
API stands for Application Programming Interface. There are numerous articles dedicated to this topic on the web, but in short: an API is a set of tools for building and intercommunicating between software applications. The name really says it all: Application, meaning software of some sort, Programming, meaning we are using this programmatically to either read, write, modify or delete data, and Interface, stating this is the interface for which the Application can be Programmed. Some folks on Quora.com gave an easy explanation, “an API is an agreement between two people, stating: If you give me this instruction, I will perform this action, or return this information”. At a fundamental level, this is how we use APIs. I want something, I ask you for it, you give it to me. Gee, why can’t life in general be this easy?
Moreover, it’s not just conversations, agreements and contracts between endpoints that make APIs so critical. APIs more importantly bring couple this sense of standardization with the applications you’re interfacing between. Chris Beach, another Quora commentator, explains the difference between interacting with a web-based application without an API versus with an API. In this scenario, imaging pulling weather data from weather.com.
An app finds the current weather in London by opening and reading the webpage like a human does, interpreting the content.
An app finds the current weather in London by sending a message to the API (in a structured format like JSON). The API then replies with a structured response.
In most cases, these API interactions are done RESTfully.
What is REST?
Not to get too in-the-weeds, but REST is an acronym for REpresentational State Transfer. REST is the most adopted architecture style for designing networked applications because it’s stateless, client-server based, and cacheable. In virtually all cases it uses HTTP for communications and, in the case of SolarWinds, JSON for standardized data formatting. One might say that the World Wide Web itself is a REST-based architecture, as it closely matches these principles (e.g., You ask for a web page, the content loads, and is presented back to you in some readable format).
You will often hear the term CRUD when discussing REST. Most RESTful applications use HTTP to post (create/update), read, and delete data, thus using HTTP for all for CRUD (create/read/update/delete) operations. The term is insignificant in the grand scheme of what we’re doing, just wanted to point it out, especially in regards to the way the data is formatted with these operations – JSON.
What is JSON?
As a simple example, the data you might get back from SolarWinds in JSON would look something like this:
We can then take this beautiful data, parse it, manipulate it and perform all sorts of wonderful tasks with it.
How this applies to SolarWinds
Let look at an example. With SolarWinds, you might wish to send an instruction to Orion asking for the status of a node, or it’s custom property values. Rather than searching and clicking monotonously through the web interface, you can retrieve the same data via a single streamlined RESTful API call. Think of the weather.com example.
You would contact SolarWinds Orion over a non-standard HTTPS port (TCP 17778), sending a request for data. In return, Orion would respond with this information in a JSON format, easily digestible, and human readable. No web browser involved. Similar to a DNS look-up, or more-similarly: a cURL or WGET request.
For example, say I want to know the IOS software details of a switch on my network. We can retrieve this data via the REST API. Simply send this instruction as an HTTP GET via the REST API. SolarWinds will receive the response, and as long as it’s valid, return the result in JSON. The screenshot below illustrates this. Rectangled at the top, I send a GET request, which is my RESTful API call. Rectangled at the bottom, you can see the response in JSON that SolarWinds sends back.
SolarWinds REST API is more maintainable and stable compared to direct SQL access. It’s excellent for automating tasks. Currently, you have read access to various Orion modules:
- Network Performance Monitor (NPM)
- Server Application Monitor (SAM)
- IP Address Manager (IPAM)
- Netflow Traffic Analyzer (NTA)
- VoIP Network Quality Manager (VNQM)
- Web Performance Monitor (WPM)
- User Device Tracker (UDT)
- Network Configuration Manager (NCM)
Certain tasks are writable as well (permitting you to make changes), which we’ll discuss in future articles. This is extraordinarily helpful for adding or updating nodes in bulk operations.
What is SolarWinds SDK?
The SolarWinds Software Development Kit (SDK) is a collection of tools and documentation to aid you in your adventures towards automation and API-driven data collection. It includes the SolarWinds Query Language Studio (SWQL Studio) to browse the SolarWinds Information Service (SWIS) schema and run test queries. It includes REST API examples, PowerShell examples, Python examples and more.
Why would you want to use SolarWinds API and SDK?
Do you enjoy repetitive tasks? Is it pleasurable to click through multiple windows and tabs just to find the status of a node, or metric of an interface? How about manually updating node properties? I just get so much joy out of these arduous tasks, let me tell you. #thingsyouwillneverhearmesay
You want to use the API and SDK to automate repetitive tasks, or to integrate with some other external script or application, or to provide intelligent reporting. A decent amount of time will go into developing the appropriate statements and scripts needed to achieve your goal, but developing workflows in this method is more strategic, likely saving you countless hours in the long term.
Some sample use cases include:
- Bulk add nodes
- Bulk add interfaces for monitoring
- Create and modify node properties
- Bulk add or modify custom properties
- Balance nodes across polling engines
- Change credentials
- Deploy application monitors for SAM
- Execute NCM script changes
- Transfer NCM configuration files
- Assign IP Addresses
- Un-manage nodes for maintenance windows
- Find unused ports in your network
If even one of the items on the list above sounds intriguing to you, I highly suggest you continue reading. This article series may not provide step-by-step details for each of these use cases, but we’ll certainly be touching on a few. More importantly, what we’re covering will be a primer, a kickstart, a guided launch, aimed to supplement and possibly enhance your SolarWinds skill-sets.
How do you get started?
So you’re interested in checking this out? Great! For the remainder of this article I’m going to show you how to get started with the SDK, such as locating the files you need and identifying the websites you should be aware of. Follow these next steps to get started.
Going forward, SolarWinds is utilizing GitHub for it’s SDK software, resources and documentation. This is because it’s easier to maintain, and more accessible for contributors. Go here to pull up the OrionSDK Wiki.
If you’re new to GitHub, don’t worry, it’s super easy to get started. But before we jump into that, let’s browse this page for a minute.
When you first land on the page, you’ll notice documentation providing basic references in regards to SWIS, SWQL, REST, PowerShell and so on. Although this says “Wiki” it’s regretfully not quite as informative as a wiki should be. That’s likely because it’s still a work-in-progress and managed by just a couple of very smart people (Tim Danner, I’m looking at you). It’s a community after all, and they do welcome recommendations, changes and bug fixes.
Near the bottom of the page you’ll see the SWIS Schema. This is very helpful when building your automation scripts.
Go to the “Code” tab. You’ll see the folder structure and files included as a part of this software package. The README is displayed on this page, telling you what is included as a part of this SDK.
– SWQL Studio graphical query tool
– PowerShell snapin
The “Samples” folder is especially interesting, because there are several PowerShell and Python examples you can reference to start building your own scripts.
If you click down into the Python folder, for example, you’ll see that the repository has moved to another location. If you’re interested in these samples, or wish to clone the repo, make sure you visit this link.
Download the SDK
If you’re using Windows and do not plan to contribute code to the Orion SDK, you can easily download a pre-compiled installer, including all of the SDK tools. This is the recommended approach for most folks just getting started. I say this because SolarWinds Orion itself is Windows-based, and most users of this application are Windows users. From the link above, you can simply double-click to install the MSI file, which bundles everything you need.
If you plan to contribute code or wish to be closer with the community, considering using command-line Git, or GitHub Desktop and cloning this repository to your local machine. To do so, choose your option to clone in the GitHub Desktop client, or download as a ZIP file. Most of the SDK will function in Mac OSX and Linux, aside from the SWQL Studio and PowerShell scripts.
Once downloaded, you’ll see the same folder structure locally on your machine as you do in GitHub repo. Take some time to navigate the various folders, poking the curiosity nodes in your brain. The screenshot above is from my Macbook.
Can I get SolarWinds support?
Great question! This SDK is provided essentially with no-strings-attached. SolarWinds does not offer a support contract option. In short, this means you must rely on community-driven support rather than paid contractual support. Don’t call SolarWinds TAC and ask why your Python script is throwing a key error; they won’t be able to help you. Much like open source projects, SolarWinds is taking a similar approach, relying on community support and expertise. Which brings me to my next point. Be careful when playing with this. You do not want to inadvertently delete your Orion database, or destroy one of your Orion pollers.
In the next article, we’ll be looking at SWQL Studio and the REST API. This means you should already have the SDK downloaded. Make sure you’re able to run the SWQL Studio (Windows-only).
Each of theses pages were references throughout this article.