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

Published Jun 20, 2013
Version 1.0

Was this article helpful?

10 Comments

  • Great article and user guide, but I was having trouble formatting the JSON output into a more readable format from the BIG-IP CLI itself. The user guide mentions using the json.tool python module, but that doesn't seem to exist on my 11.4.1 installation, so I instead used the following perl module, by piping the output of each of my curl statements to the following command....

     

    perl -0007 -MJSON -ne 'print to_json(from_json($_, {allow_nonref=>1}), {pretty=>1}), "\n";'

     

     

    Much more readable!
  • Hi Joe,

     

     

    The command listed to start the icrd daemon has a typo:

     

    "modify sys service ircd add"

     

     

    Thanks!
  • Can you please help to get Schema details of REST APIs. ? may be XSD file for the same or URL if file is on server side.
  • Hi Joe, Is it possible to use the iControl REST API if you are not in the Administrator role. I would like to use the API to check Pool Status by I keep getting '"code":401,"message":"Authorization failed: no user named svc-hpoo-tm found. ' This user works fine using SOAP....Thanks
  • Yes, you can add non-admin users to REST framework to use those users to access REST services.
  • In case you are interested, I wrote some python code to create LTM VIP's using the REST API. Tested on a bigIP running OS version 11.5.1. Here is the link: https://github.com/ericjmcalvin/f5_bigIP_LTM_VIP_creation Still have a few TO-DO's but I am working on them and will post the updates once they are tested and ready.
  • Do folks typically send the REST API calls to the mgmt IP or to a floating self-IP setup to accept? If mgmt IP, how do you handle LTM pairs setup in HA since there isn't a virtual mgmt and each LTM device in the HA pair has their own mgmt IP. How do you ensure that the API calls are going to the active LTM instance?