Introducing a RESTful interface for iControl

iControl isn’t just SOAP anymore…

No, iControl isn’t getting lazy.   While taking it easy is an important part of life, I’m talking about the other kind of REST.   REST, or “REpresentational State Transfer” for you technically inclined, is a style of architectural principals with which you can design web services that focus on a system’s resources.  It also defines how resource states are addressed and transferred over the network.  REST is really a “style” of getting and setting resources and doesn’t define the underlying communications.  Most implementations out there make use of HTTP and JSON as a content format, which is what we’ve chosen to do as well.

There are plenty of articles on the web that compare and contrast SOAP and REST, so I won’t get into those here.  I’m also not going to go really deep into the principals of REST as you can find dozens of those easily with a web search.   In this article, I’ll discuss how we’ve chosen to implement our REST interface for iControl and give you some examples on how to use it.

Oh, and don’t get any ideas that our SOAP based interface is going anywhere.  We are creating our REST interfaces as an alternate method for performing automation and monitoring.  We don’t currently have plans on ceasing development on our SOAP interface.

iControl-REST

The REST interface for iControl was introduced in BIG-IP version 11.4.  For this release, we are considering the feature as “Early Access”.  Call it beta or whatever you want.  But what that really means is that it will change in our next release.  We are using this release for feedback from the users out there to find out what works and what doesn’t.  Several key features are not implemented yet (for example versioning) which we have targeted for an upcoming product release when we finalize the implementation.

Ok, with that said, now we can get into the details.

iControl-REST, like it’s SOAP counterpart, is implemented on HTTPS and uses the same authentication and authorization roles for user access.  We support the following HTTP commands:

• GET - for retrieving (ie. Querying the status of a Pool)
• POST - for creating (ie. Creating a Pool Member)
• PUT - for updating (ie. Changing the load balancing method on a Pool)
• DELETE - for deleting (ie.  Deleting a Virtual Server)

And, the format of the requests and responses is JSON.

Starting the iControl REST Service (icrd)

Run the “modify sys service icrd” TMSH command to add and start the iControl REST service.  Notice the nice “EA” warning.

root@(BIG-IP1)(…)(tmos) # modify sys service ircd add
WARNING: This early-access feature comes with minimal
documentation and testing.  Version control is not implemented;
therefore any scripts that you write using this API version
may not work with subsequent releases.
root@(BIG-IP1)(…)(tmos) #

Once the service is running, you can use the “show sys service”, “stop sys service” and “start sys service” TMSH commands to monitor and control the status of the iControl REST service.

Writing Your First Script

Since iControl-REST is just using HTTPS, you can use any scripting technology you heart desires.  For this article, we’ll use the command line tool cURL.  It’s cross platform, so you should be able to wrap a bash script for Unix, Mac, etc or PowerShell for Windows around it very easily.

Use the “-u” parameter to pass in the user credentials, the “-X” parameter to specify the HTTP method, and the uri for the resource you wish to access.

curl -k -u user:pass -X http-method uri

The URI format is as follows

Module URI

https://management-ip/mgmt/tm/module

This access all of the sub-modules and/or components under the given module (ltm, gtm, etc).

Sub-module URI

https://management-ip/mgmt/tm/module/sub-module

This access all of the sub-modules and/or components under the given sub-module.

Component URI

https://management-ip/mgmt/tm/module[/sub-module]/component

This accesses the details about the given component.  The tmsh Traffic Management Shell Reference documents the hierarchy of modules and components, and identifies the details of each component.

Example

This curl command will query all of the information about the ltm module.

$ curl -k -u user:pass -H “Content-Type: application/json” -X GET https://bigip_ip/mgmt/tm/ltm
{
  "currentItemCount": 22,
  "items": [
    {
      "reference": {
        "link": "https://bigip_ip/mgmt/tm/ltm/auth"
      }
    },
    {
      "reference": {
        "link": "https://bigip_ip/mgmt/tm/ltm/data-group"
      }
    },
    {
      "reference": {
        "link": "https://bigip_ip/mgmt/tm/ltm/dns"
      }
    }
    ...
  ],
  "kind": "tm:ltm:ltmstate",
  "pageIndex": 1,
  "partition": "/Common/",
  "selfLink": "https://bigip-ip/mgmt/tm/ltm",
  "startIndex": 1,
  "totalItems": 22,
  "totalPages": 1
}

User Guide

For this release, we have provided a User Guide to assist in getting started with using the new REST interface.  It can be downloaded from this link:  iControlRest-UserGuide.pdf.

We would love to hear your feedback on using iControl-REST.  Any and all comments and questions should be posted to the iControl group.

-Joe