iControl REST 101 – Creating Objects

If you’ve been following along so far you’ve gotten an idea about what iControl REST is all about, seen how to get up and running so you can send commands via cURL to the API, parsed some responses, and even got a peek at viewing some useful Virtual Server data. If you haven’t been keeping up, I recommend checking out the first two parts of the series so you’re caught up.

iControl REST 101 – What is iControl REST?

iControl REST 101 – Getting Started

Now that we’ve figured out how to communicate with the REST based version of iControl let’s take it a little further. So far we’ve listed some available methods and information about a specific object. What would be nice now is to be able to not only list objects, but also to create them.

Last time we looked at listing a virtual server. That’s something we’ll get to eventually but there are a lot of options for virtual servers. Let’s start with something simpler but no less useful and ubiquitous, like a self IP. First we’ll look at the list command and then the create command.

Before we even get there, however, I need to give a nod to Jason and his awesome blog about jq. jq, for those that haven’t found it yet like me, is a fantastic little program. It is a single binary so it’s easy to distribute or grab, and it does some fantastic JSON formatting quickly and easily. For some more examples of using jq take a look at Jason’s blog post, or just keep reading, because I’ll be using it from here on out.

Let’s take a look at what jq does for us. If we want to list the self IP addresses on our device it would look like this, with the following, not so pretty to read, output:

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/

So, let’s look at how you would list the self IP addresses on a device using this handy new tool. I want to break this out into readable text based on the JSON formatting, and I also want to only list a particular self IP, to narrow down my results. Since the results from iControl REST are broken out into an array of items that becomes easy with jq. I just request the index of the item I want and it returns only that info in pretty, formatted, legible fashion:

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ | jq .items[4]

How much better is that, right? So that’s jq and listing again. But what about adding? To add it’s actually very similar. You’re going to send a call via cURL to iControl REST, but this time instead of getting JSON formatted data back, you’re going to send JSON formatted data to the device. To do so you have to know what data to send and what format to send it in. Fortunately there was a method to my madness with reviewing what it looks like to list an item.

If you look at the return info we got in our jq formatted self IP get, you already have all the data you’ll need to send, and even the format in which it needs to be sent. See the name value pairs? Blue text on the left is the name, the value is on the right of the colon. To create an object with iControl REST you simply send a request to the device using the proper formatting and filling in the required fields to create an object. For the self IP we just saw in the list example above that data would look something like:

"name":"cw_test","address":"10.10.10.2/8","vlan":"internal"

The rest will get set to defaults for the device. The other important part about sending a create request as opposed to a list request is letting the device know you’re attempting to create an object. The API knows this based on the request type. For a list we used a standard GET, meaning we didn’t specify anything in cURL because that’s the default. For a create we’re going to use a POST. We also want to add a Content-Type header. This means our cURL command will change slightly. The base command to add any self IP, minus the definition data required for the object you’re creating, is (Don’t run this yet):

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ -H 'Content-Type: application/json' -X POST

To actually execute this and add the IP we simply take the above command and combine it with the data, and run it. I’m going to change the name and increment the IP address to 10.10.10.3/8 since I already have a .2. Then all we do is run it, then list the IP to make sure it worked and looks correct, which means running the following two commands:

Create:

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ -H 'Content-Type: application/json' -X POST -d '{"name":"cw_test2","address":"10.10.10.3/8","vlan":"internal"}'

List:

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/ | jq .

Which gives this, commands and all:

As you can see there’s not a whole lot to it once you get comfortable with the JSON formatting and the data that’s required. For the record, that’s pretty much the same as running this via tmsh from the command line, minus the JSON formatting bit. This means that once you’ve mastered the command line tools, you’re already a pro with iControl REST … but I’m pretty sure I’ve mentioned that a few times already.

So there you have it, a brand new self IP created on your device via iControl, and all with a single command via cURL. Automating F5 devices has never been easier. Go play around and tune in for the next installment on modifying items next week.