Port 17777: Introduction to the SolarWinds API

hello everyone I'm Patrick Hubbard head geek at SolarWinds with today's presentation port 1777 introduction to the SolarWinds API when we first started planning thwack camp I got really excited this year because I wanted to do this last year I didn't have a chance and the API has come such a long way and so many of you have had so many questions that I think you're really gonna get a kick out of this I certainly have to just kind of a quick overview here of our API we'll do an invoke here I'm gonna talk about that a little bit I'm gonna give you a brief history of the Orion platform so you sort of understand how all of this came to be I'm gonna introduce you to Swiss that's the SolarWinds information service we'll talk about how to get started using the API I'm gonna give you an introduction to swickle which is the SolarWinds query language and then we'll talk about how you can not only read data but also create update and delete it using crud actions that are also available using Swiss so before we begin just a little workplace safety reminder the API provides an amazing amount of power so you can do things like automate manual processes right now that may take you all day and knock off and go home early which would be great you could also blow up your ride install and delete all of your data which would not be awesome so just a couple of recommendations as you start to work with this do set up a dev instance of Orion for your experimentation do not try untested powershell scripts that you download off of the internet on your production systems do make a backup of your ryan database don't make your first project something that's doing node creates inside of loops that probably would not be a good thing do dream really big many of you have got some great ideas for automation projects and this is a chance to really take a take a crack at that and and see how to how to really make your Orion do some pretty cool things and just get in there and have some fun and the last thing of course give us plenty of feedback and participate on the thwack forum okay so let's start with a brief history the Orion platform and I like to really take a second anytime I talk about Orion and NPM and now Sam and so many of the other modules because it's easy for me as an old-timer to sort of speak about Orion and NPM interchangeably but in this case we really are talking about a set of core services that underlie all of these different applications and modules so we're talking about Orion and in the beginning NPM began Oh Ryan and for those of you who have been with the company for a really really long time as customers NPM started as one of the wind' gooeys inside the engineers toolset about a decade ago and customers said hey this is great we love the alerting and reporting in charts and graphs but it would be nice if it ran on something more than my laptop and they wanted it to run on a server 24/7 so the first version of that that server based version of NPM was called Orion and it was a visual basic website bolted directly to a sequel server but after several thousand customers and those customers started to get bigger and bigger and there were a lot of modules added it was time for a rewrite and so the core services were actually broken out as the Orion platform and then NPM became just another module sitting on top of those common services and that's things like alerting and reporting and charting and graphs and mapping and a bunch of other features the other thing that happened was that I Ryan truly became in Tier so instead of being bolted directly on top of the sequel server everything from web the polling and reporting and then even the coordination components between different elements all started to communicate using service layers and those started working over port seventeen seven seven seven and I used that port number because you might have occasionally seen that in an error message which basically just tells you that the information services are running or maybe it's blocked maybe there's an Akal it's preventing access and you have a remote website but anyway so those started running on port seventeen seven seven the main thing that happened was this allowed tremendous scalability and improvements in performance and flexibility for larger and larger customers and then after a couple years ago we started making the API available and then actually started producing a full SDK which is what we're gonna be talking about today so the main thing here to keep in mind is that what I'm gonna be showing you and what this API is about is not a special little add-on to make it easy for customers to access data these are actually the guts of how Orion is communicating internally so it's the same sort of industrial level heavily maintained core technology that you would expect instead of just a little add-on SDK that maybe somebody maintains so to start off let's talk about Swiss that's the SolarWinds information service it is not cheese it is not a country it's the data access layer used by SolarWinds products to communicate it's a hybrid of object-oriented and relational features it supports a sequel like language that we'll talk about a little bit later called swickle but the main thing is it allows cross-boundary whether it's internal applications on the same server cross protocol but even cross operating system integration the other thing that you've probably never thought about is that you were dealing with a Swiss login all the time every time you open up Network Atlas and it asks for the server name and your Orien logon information that is actually a Swiss logon page and then what's really cool in the latest release is it now it actually supports a rest and JSON interface and I'm actually going to do a demo of that for you here in just a second the main benefits for using Swiss to your integration is first of all it already provides a credential provider so it's using an Orion account that's already inside of Orion so you don't have to create a your own security layer on top of that that also means that you get a Ryan account limitation features built in out-of-the-box so if you want to have differentiated views for different end users you don't have to create a separate service for each one with a different set of limitations you can provide a common service and then just limit what those accounts are able to see and the results that come back will automatically be limited based on those account limitations the best thing from my opinion and I once upon a time built all of our demo system and have abused Orion databases in ways that I don't think you guys can even begin to imagine is that you don't have to worry about the database schema anymore because you're dealing with the objects and an object dot notation reference language we can make changes on the backend that will not break your applications that will not break your integrations because you'll you're not dealing with the database schema anymore it also makes it way easier to figure out how things work and then the other cool thing about it is is it's meta and that the Swiss tools and API is allow you to query information about objects not just their data so as you explore them and extend the capabilities of your integrations you can actually quickly figure out how things work so where is Swiss I mean if you look at your Orion install you'll see lots and lots of different services everything from JMX bridges to the job scheduler and data collectors but the ones to look at are the information services and the Orion module engine and Swiss is actually being provided by just those services it listens on to ports and it provides a identical operations on both the first one you already know that 1777 and that's a net dotnet tcp-based it's really high performance but it's Microsoft only so then the second port that you may not have seen is port seventeen seven seven eight and that is actually a WSI soap port and over HTTP and that allows for interoperability with other programming languages and if you want take your favorite wisdeth explorer and check out these urls right here you can actually pull the wisdoms down from both of those although in a minute you're gonna see the documentation that you really don't need to but it it allows you to explore those directly and doesn't expect you to have to know everything about them to start experimenting with the data okay so the first thing to do is you're gonna need to get the sdk so let's talk about how to get started with that if you happen to know this URL up here to get directly to the thread you can use that so for me the easiest way to do is i'm just google SolarWinds sdk and then click on the first link that comes up and that will take you right here to the sdk information now there are a lot of other threads and this is actually in the SolarWinds lab section of thwack under the Orion SDK group but right right here across the top you can actually see all the past and current versions the current version is 1.7 and just click right here to download it I'm gonna be using that one for this presentation and then of course the forum is right there in the lab space and it's monitored by a number of folks inside the company so definitely get in there and give us your feedback on how it's working for you so the thing to do there is to download the zip file that zip file is going to include an MSI file which means you're gonna need Windows to unpack it but there's a reason for that because it's going to install a windows-based tool which is the Swiss GUI studio and I'm gonna actually give you a demo of that but it's also gonna unpack all the other elements of the SDK and so you don't need Windows to integrate with Orion so if you're using Python you can just copy all of those source files and the examples off onto a Linux box and really start having some fun but you do have to at least unpack it onto a Windows machine it's also kind of handy because then if you put it on the Orion server itself then you might be able to do some quick PowerShell examples and rest of it to make sure everything's working well and then I definitely recommend that you read the SDK applicability PDF first it's only three pages long and it can really give you a great sense of how to get started and I'll talk about it later again but the documentation that's included with the SDK is just really really good so now you've got your MSI unpacked on the machine what's in the SDK well the first thing that you're gonna get is swickle studio so that's the object Explorer it's the query test environment and it actually will connect like anything else using Swiss using your Orion account and it allows you to visualize the object model and inheritance and there's a bunch of tools I'll show you how that works and it'll let you actually also test your view limitations as well because you can log in under different account context there's also a number of high-level clients that are already built for you there's a snap in for PowerShell and there's one for Python and then there's a sample code for everything from c-sharp to Java Perl PowerShell and VB the other thing that's really cool is you get complete schema documentation in the HTML format okay so the first thing that we're going to talk about here is swickle that's the SolarWinds query language and it's a lot like sequel but I think it's better first of all it's based on a read-only subset of sequel which can keep you out of a lot of trouble but it supports a lot of powerful constructs from sequel so select including from and where and grouping and having you can do ordering you can do joins with differentiators for the type of joins you can do top in distincts you can do sub queries and you can do that also from and inside of joins it also supports a lot of attribute functions like sum and maximum average accounts so that if you're doing reporting you can do roll-ups supports regular functions to make sure that it keeps you out of trouble with null values worried about things like basic routing that sort of thing it does not support select star from and I'm gonna get into that in a minute because there's a included sort of out of magic inheritance as a part of swittel so it doesn't support star you do need to explicitly name the fields that you're looking for and it doesn't support update insert and delete but we do support credit crud actions for all of those as well it certainly doesn't support drop the other cool thing about swittel is that it has features that really aren't a part of sequel the first one of those is navigation properties so there like I mentioned there serve an automatic join for related objects so for example if you're doing a query on interfaces then interfaces are always attached to a node so with the dot notation you can go from the interface out to node and then to a property out node like caption without doing a join now if you want to do a join for a particular reason and I'll actually show you an example that in a minute you can certainly do that but it makes navigating that an awful lot easier the other thing that it does is it lets you do row windows really really easily so especially if you have 10,000 nodes you probably are not going to want to return all 10,000 at once it makes it easy to cut and slice those up into chunks you can work with and it goes right after the order by clause so it's familiar like sequel and you get this intuitive object dot notation and the other thing is that it's read-only so you can't really break anything with it so it's a great way to start working with Swiss so I'm going to ahead and launch the swickle studio here and it's asking me for a logon so it's gonna ask me for a server name the type of server that it's connecting to so that's gonna be the API that it's going to use in this case and then a password and you know guess what I stuck with that and then blank on this one it's going to give me a connection and now I can start exploring the objects on that server you can see here this one's got APM installed and a couple of other modules and so as I scroll down here you can actually see all of the different objects that are available to you in that install now this list may be different depending on what's installed and things like your custom properties and that sort of thing you've created but for example I can just go in here and start exploring right so here's my a Ryan dot nodes object and then here's all the properties of Orion nodes but beyond that I can actually also get my linked properties and then the associated ones as well now I know this seems like it could actually get to be pretty complex there is a entity inheritance graft included which is really great so as you're learning about this you can use this as a tool to kind of scroll through here and figure out how things are associated with other objects but I like to just get started so let's say we're gonna look at our Orion nodes list here if I right click on this it'll say generate a select statement and it's going to actually go out here and generate a swickle select statement an awful lot like what you'd get in the sequel manager but I could also if I wanted to create the select statement with all the inherited properties as well so it'll actually show you how to do that as well and then I'm just going to execute that and an ounce gallon add on to the server and pulled all of the data that I asked for with that swickle command I mean that's pretty cool and it's really really powerful I can run this again I'll just cut a whole bunch of these properties out here and we'll just re-execute that to prove that it in fact is executing only what I'm asking for and here you can see I can came back with a subset of that data so the swickle studio is a great way to get started the other thing that'll let you do is and let you set parameters for parameterised query testing I'm not gonna go into that because this is not actually a programming guide but it's definitely a part of the admin guide which you should take a look at but that'll allow you to test parameterised queries as well so that is swickle studio now we've talked about this a little bit in terms of a basic select like this but I also mentioned that these were available using a JSON REST API as well so let me show you what that looks like so over here I've got my Orion set up and I've got a bunch of nodes on this system and one of them I'm gonna pick on just a little bit here or this energy-wise switch sitting out here I can see all of its details and if I wanted to interact with this thing using rest there's a bunch of ways that I can do that but the easiest way is that the service is provided through a couple of different URLs and again this is all in the main admin guide but essentially I'm going to give it at the URL to that service which is running in this case on port 17 seven seven eight remember that's your interoperability port and then I'm providing a query so in this case it's I'm gonna ask it for all of my polar information with the particular ID and I'm gonna limit it to three rows I'm gonna grab that now I if I was integrating this I probably would either be using PowerShell where I write a custom application or something else but I'm gonna just use the web browser here natively will get that data and it comes back with my results here so these are the Polar's that I have running on this system I've reinstalled it a couple of times so I've created a couple three different polar IDs but that swickle is running directly off of that information service API so again there's a number of different ways that you can do that this was a quick way that I did it for this example another way that you might do it this one I've got I think you might have noticed down here I've got a number of a number of nodes on this system if I wanted to list all the nodes that might actually take a really long time so this one just just gonna give me the first 20 nodes so if we look at this query I'm gonna ask it for the caption IP address no description vendor but I'm also asking it for this value here a custom property called boss okay and if you watch the last lab episode you'll remember what that was from from Orion nodes and then I'm doing a join out to the nodes custom properties and then I basically can attach that I give it the the Equality for that join and then I'm also doing an order by and I'm limiting the number of rows if I get back so in this case I'll paste that same thing right in here and now I have the top 20 nodes that came from that server so I can actually see the node caption description if there was one the vendor and a little bit of other information about it so again that was a really quick way to get data using swickle and I didn't have to do any other integration it was just available for me right there so if you think about how handy that would be if you need to provide a Ryan data to an external team you're you basically just give them a URL and the basic swickle that they would execute you use view limitations on the account that you provided them and then maybe put that account into a limitation group that's associated with Active Directory and if for whatever a person that and if for whatever reason that person outside of your organization is taken out of your your company they're going to close their Active Directory account and they're all so going to be blocked from the integration using the API so really great integration security using Swiss okay so what if you want more what if you want to actually do creates and updates and deletes on objects well Swiss now supports crud actions which is really really powerful have you wanted to do things like add nodes or n interfaces on nodes it the Swiss automatically supports the crud actions to make that easy now the forerunner to crud before version 2.5 was something called invoke and it's still supported and it was basically a library of verbs that could be called on a Ryan object so for example if you wanted to do an acknowledge on an alert status or you wanted to unmanage or re manage a node you could do all of those with the invoke structure and it's it's still in there and it does some things that are really pretty powerful as well like discovery and a couple of other things where you really want to let the platform do the heavy lifting for you but you guys said you wanted more and so with 2.5 now we support cred for almost all the objects in the system's it's limited pretty much only by your imagination and you use a set of you are eyes to address your entities and so that basically again would be the basic host and endpoint and then the entity type basic filter information and then optional key filters for sub on objects so for example you'd have a Ryan Ryan nodes the node ID now then the interfaces on that ID and then an interface filter for interface to would be interface to on node one then when you call an action that action is going to be applied to that one specific object so you get all the power you need to shoot yourself in the foot but remember you asked for it so let's do a quick demo of how that works now I had this note up here a minute ago this is that energy-wise switch right so I added a custom property down here called boss ok and I had a view for a manager that literally had in another video that just had one green button for the things that he could see but we allowed him to see a few other things with this custom property but let's say I want to update this custom property using a crud action so the way that I'm going to do that in this is actually with PowerShell so let's take a look at that script so this is a sample script on how to do this using an update property on a node and this in fact is coming directly from the SDK I've modified it slightly to make it a little bit easier to do what I want to do specifically here but it's a great way to get started now the point that I want to make about this is that this thing is only of 24 lines long and really if you wanted to just create hard create your the URI that you were calling using something other than PowerShell and you didn't want to have parameters that automatically built a string for you and everything else if you just wanted to build that through your own mechanism and execute it this would be one line long now the other thing that's happening here is I as I mentioned there are some pre compiled tools for this high level tools and so one of those is this the PowerShell snap in for Swizz which has already been applied here to my powershell and again instructions for setting that up just it's a couple of steps and it's also in the admin guide so what's basically going to happen here is I'm going to create a URI for this custom property and then I'm gonna pass the property that I want to apply to that and in this case the snapping is smart enough to figure out how to do that for me because it's it operates at a pretty high level so what I'm gonna do is node ID six seven two which I happen to know is the node ID of this node up here I can also see it right up here so node six 72 this is my server end point and my logon information i'm password is blank in this case and i'm just gonna set the bot the parameter boss okay equal to true and then that's gonna build a uri for me and then it's gonna call the set swiss object method and then pass in everything that it needs to execute that so let's go back over here to powershell and i showed you with the one that said true but we're gonna set it to false because right now that value is true so let's come over here to powershell we're gonna execute false I'm gonna refresh my view and you can see that boss okay custom value is now set default I could also see that through the REST API if I wanted to got a little code here that's actually going to add the limitation for select all of the values where the boss property is set to true grab that I might throw that into my web browser so here's all of the nodes where the boss okay value is true and you'll notice that the that energy-wise switch is not here this is the 40 the 4506 is so if we want to add that guy back in there let's run the other powershell script that sets that to true I'm gonna refresh and look at that there's my energy-wise 35 6d and we can also see that in the web interface 35 60 and we can also see that right here in the details boss okay equal to true so that's just a really simple example of how you can actually use crud actions to not only read data using the Swiss API but actually do create updates and deletes as well so again just a quick summary there the actions again are based on object you are eyes they're really easy to look up and they're in the documentation definitely check that out you can only specify a single entity per uri so if you need to make a bulk update you'll first want to do a select get a list of objects and then iterate over the results to make all of those changes definitely use verb for high-level functions things like interfaces discover interfaces on node are built in there for you so you can let the platform do the heavy lifting and then the last thing is definitely our TSM read the SDK manual it's only 40 pages including the examples there's lots of code that you can skip that doesn't apply to you and I'm not picking on you visual basic but what's really great is this was written by the team that actually wrote the code so it is really danced into the point so they've all been tested and it's regularly updated along with each release that's using the internal SDK so what are you waiting for go ahead and download this today and get in there and check it out this is especially applicable to you if you have already hacked the Orion sequel database directly because this is so much easier to you and the other thing is that it really does include secret sauce that you just don't have access to reverse engineer for example using the API to do interface discovery on a node he is actually calling the same code that gets called through the GUI or through discovery so that's something that you wouldn't be able to do so you're not only at having access to the data but you actually have access to call functions on the platform itself do remember that it's not a supported product feature so you can't call support to get help with it it does however have a very active thwack group and remember and this is not a hack I mean this is direct access to the same production plumbing that Orion and its product family uses itself to interact between layers modules and even external applications it's very well documented and it's actively developed with each release I mean it's from the Guru's that build the Orion platform they've been with this product for years and the level of streamlining and functionality that's available in the SDK is extremely mature for something that's really only been exposed to customers for a a little bit over a year now and the last thing is like so many SolarWinds products and tools it's completely free so what are you waiting for go ahead and download it right now while I'm speaking go ahead and google SolarWinds sdk start the download now installed on your system and check it out so I'm really looking forward to seeing you on the thwack forums and to see all of the creative hacks that you all come up with using the SDK so again I'm Patrick Hubbard and thanks for attending today's presentation

Channel: solarwindsinc

Views: 17,674

Keywords: SolarWinds, API, SDK, programming, automation, services, architecture, CRUD, SWIS, SWQL, 17777, thwackCamp, thwackCamp 2013, Head Geek, Patrick Hubbard

Id: 8BCxmcfVnNw

Length: 28min 27sec (1707 seconds)

Published: Fri Oct 11 2013