Getting Started with iControl: Interface Taxonomy & Language Libraries

In part two of this article in the Getting Started with iControl series, we will cover the taxonomy for both the SOAP and REST iControl interfaces, that were discussed in the previous article on iControl History, as well as introduce the language libraries we unofficially support on DevCentral.

Note: This article published by Jason Rahm but co-authored with Joe Pruitt.

Taxonomy

The two interfaces were designed in different ways and with different goals.  iControl SOAP was developed as a functional API behaving very similar to a Java or C++ class where you have interfaces and methods included within those interfaces.   Interfaces roughly related to product features and for organization, those interfaces were then grouped into larger namespaces, or product modules.   To get a little more specific, iControl SOAP implements a RPC (Remote Procedure Call) type model.  To make use of the APIs, one just instantiated an instance of the interface and then used functional (create(), get_list(), ...) and accessor (get_*(), set_*(), ...) methods with it.

iControl REST on the other hand, is based on a document model where documents are passed back and forth containing all the relevant information of the given object(s) in question.  This interface makes use of the HTTP protocol's VERBs (GET, POST, PUT, PATCH, DELETE) for action and URIs (ie. /mgmt/tm/ltm/pool) for the objects you are manipulating.  Instead using methods to perform actions, you use the associated HTTP VERB to trigger the action, the URI to denote the object, and the POST data or Query Parameters to indicated the objects details.  iControl REST is currently modeled off of the tmsh shell which uses similar modules and interfaces from SOAP (with different abbreviations) in it's URI path.

	Module	Interface	Method
iControl SOAP	LocalLB	Pool	get_list() create() add_member()
	Networking	SelfIP	get_netmask() set_vlan()
	Module	Sub-Module	Component
iControl REST	ltm	pool	<pool name>
	net	self	<self name>

Now for some simple examples using the SOAP and REST interfaces using python libraries. Don't worry if python's not your thing, we’ll cover some perl, powershell, java, and Node.js as well in the following articles in this series.

### ignore SSL cert warnings
>>> import ssl
>>> ssl._create_default_https_context = ssl._create_unverified_context
### SOAP
>>> import bigsuds
>>> b_soap = bigsuds.BIGIP('172.16.44.15', 'admin', 'admin')
>>> b_soap.LocalLB.Pool.get_list()
['/Common/myNewPool2']
### REST
>>> from f5.bigip import BigIP as f5
>>> b_rest = f5('172.16.44.15', 'admin', 'admin')
>>> b_rest.ltm.pools.get_collection()[0].name
u'myNewPool2'

Note there really isn't much difference between the two iControl interfaces when it comes to the client code. This is the beauty of libraries, they mask the hard work! We'll dig into the code more in the next article. so don't worry too much about the code above just yet.

Interfaces & Objects

In the above section, we briefly outlined the high level taxonomy between module and interface. There are literally thousands of defined methods for the SOAP interface, all defined and published in the iControl wiki on DevCentral. For the REST interface, you will want to reference the iControl REST wiki as well, but you will really want to become intimate with the tmsh reference guide, as a solid understanding of how tmsh works will make a more favorable going.

Language Libraries

Raw SOAP payload is out of the question unless you enjoy pain, so a library is a given if using the SOAP interface. But even with REST, as easy as it is to interact with interface directly, the fact is if you aren’t using a library, you still have to create all your JSON documents and investigate and prepare all the payload requirements when manipulating or creating objects. When selecting SOAP or REST, the reality is if you’re going to build applications that utilize iControl, you’re definitely going to want to use a library.

What is a Library?

Depending on the language or languages you might use, a library can be called many things, such as a package, a wrapper, a module, a class, etc. But at it’s most basic meaning, a library is simply a collection of tools and/or functionality that abstracts some of the work required in understanding the underlying protocols and assists in getting things done faster. For example, if you are formatting an office document and changing the font size, color, family, and bolding it on select words throughout the doc, it could be painful to do this if you have to do it more than a few times. You could record a macro of these steps, and then for each subsequent task, replay that work via the macro so you only have to do it once. In a roundabout way, this is what libraries do for you as well. The common repetitive work is done for you, so you can focus on the business logic in your applications.

What Libraries Are Available?

There are several libraries available, some languages having more than one to support both iControl SOAP and iControl REST, and at least one (like python) that has several libraries for just the SOAP interface. To each his own, we like to expand the horizons around here and equip everyone for whatever language suits best for your needs and abilities. We could list out all the libraries here, but they are already documented on the programmability page in the wiki, at least the ones we are directly responsible for. Joe does a lot with PowerShell and Perl, and I with python, and we do have quite a few community members well versed in the .Net languages and python too, though there is some support for java and ruby as well. On Github I've seen an iControl wrapper for the Go language, and I seem to recall some love for PHP a while back. 

Now that we're through the history and some foundational information on the SOAP and REST interfaces, we can move on to actually building something! In the next article in this series, we'll jump into some code samples to highlight the pros and cons of working with SOAP and REST, as well as show you the differences among a few languages for each interface in accomplishing the same tasks.