iControl REST 101: Getting Started

So you’ve heard of this iControl REST thing, have you? You’re excited at the idea of a simple, light weight API that allows you programmatic access via tried and true tmsh commands with which you may already be familiar? Whether it was in the earlier iControl REST 101 article or elsewhere, your interest is piqued and you’re now looking to start digging in. Excellent, let’s get started.

Links of Interest

First you’ll want to save a couple of very handy links. These are sure to aid you in all of your future iControl REST endeavors, so take note:

iControl REST On Cloud Docs– DevCentral is the place for all things programmatic and beyond the box when it comes to F5 technology. iControl REST is no different in this regard. The documentation, articles and examples on iControl REST available on DevCentral are already handy and will continue to grow as the community brings the power of this fully functional API to bear. No Death Stars were harmed in the making of that last sentence. Whether you’re looking for intro level docs or more advanced examples, this is a good place to start, so keep it close at hand.

User’s Guide – If you’re looking into iControl REST programming and haven’t seen the user’s guide yet, you’re doing yourself a disservice. Chalk full of helpful examples, explanations and code snippets, the user’s guide will be your faithful companion on your iControl REST journey. Put together by the PD team responsible for bringing you iControl REST, you’ll find huge amounts of useful information here.

Now you’ve got the documentation at the ready and you’re eager to get started. Excellent! The first step is to take a look at what an iControl REST call actually looks like. You can write all the code in the world in whatever language you’re most comfortable with, but you’ll need to know what calls to send and what to expect as a result before it amounts to much. Fortunately getting started with iControl REST is immensely simple. Because this is a REST based API there’s very little overhead or setup needed. All you really need to be able to do is send GET and POST requests to a web service. This can be done either directly from the command line with cURL, via a browser plug-in, a script, or anything else that allows you to build a custom body and send it via HTTP.

Examples

For these examples we’ll be using cURL, so let’s take a look at what that looks like. The first thing you’ll want to do, most likely, is get a listing of some different commands you can run. Of course, as I’ve said many times now iControl REST follows the tmsh structure, so if you’re familiar with that it will be nothing new. The rest of the setup, however, may be interesting. First we’ll use cURL to send a basic command to the BIG-IP asking it for a list of management resources. For this we use the –s (silent) and –k (insecure) cURL flags to strip out all status/usage info and allow for insecure SSL negotiation. We’ll also use –u to supply a username:password combo. This will get us into the test device and allow us to get an actual response. The constructed command looks like this (Keep in mind the output will vary per device based on version, configuration, etc.):

curl –sk –u admin:admin https://dev.rest.box/mgmt/tm/

That isn’t hugely useful to a human, however, since it’s not overly readable. Given the formatting, however, it is pretty simple to break at each comma and insert a newline. We can do that easily from the command line to make this much more human readable. Here’s the appropriate sed string appended to the original command from above. Note that this is a bit different given that I’m running on a Mac, so I tweaked the regex replace a bit to suit my needs, though it should function fine on either Linux or OSX.

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/ | sed 's/,/\'$'\n/g'

What you’re seeing here is a list of available resources that you can query via iControl REST. Each of these is a part of the underlying tmsh system. This list goes on and on, the above is just a truncated snippet. If you’re looking for specific commands, check out the tmsh documentation and have at it. From this point it’s trivial to start sending commands that might get you useful information back from your device. Whatever you can think of you can send, for the most part. How about something handy like listing all virtual servers on your device and their associated info? Be warned that the below command will likely get you a huge amount of output on a device with a decent config. To list all virtuals you would do something like:

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/cloud/ltm/virtual-servers | sed 's/,/\'$'\n/g'

Again, this goes on and on, the above is just a snippet. Seriously,  Note the familiar JSON formatting here. You have an item, identified by the address, and a list of name value pairs of info related to that item, including sub lists where necessary. This should look familiar to anyone that’s dealt in this kind of structure before. It is this simple, easy to parse formatting that is part of what makes iControl REST as widely applicable and easy to pick up or integrate as it is.

There you are, a couple easy commands and you’re already connecting to your BIG-IP via iControl REST, grabbing data, and ready to start making changes and writing code. When I said iControl REST was light weight and simple, I wasn’t exaggerating. In the next installment of this series we’ll continue with the cURL usage but begin to make modifications to objects on the device.