iHealth API Part 2 - An Introduction to REST

In the last article, we got some ideas of the kinds of data that iHealth can provide by exploring the wealth of information through a standard web UI.  This is a quick easy way to get answers about a couple of your F5 machines, or to do a one-off check of something, or if you are looking for a particular problem, or working with F5 Support to resolve an issue or answer a question.

If you have a couple machines, or maybe many many more, however, and you want to do something periodically, like, say, check for new Diagnostics results (remember, we generally update them once a week), then you'll quickly find that opening your browser, logging in, uploading the QKViews, and then reading through the Diagnostics is not necessarily the most efficient method.  It can become annoying and tedious for even one or two machines.

Since iHealth is a web application, it made the most sense to make the iHealth API a web API as well.  There is a dogs breakfast of different types of web APIs, but one of the most prevalent conceptual frameworks in use today is called Representational State Transfer, or REST.  The wikipedia entry on Roy Fielding has links to his dissertation if you want to up your street cred significantly.

REST provides a nice clean way of retrieving, modifying and deleting things using HTTP in all (well most all) of it's glory.  It's hidden from most users (as it should be), and unless you are a web developer, or someone who is dealing with web traffic a lot, there isn't any reason you would need to know this, but the HTTP protocol specifies a number of different ways to ask the server to do something.

Now that you will be working with an HTTP API, you're going to have to know a little more about HTTP.  Generally the two verbs that a developer will be familiar with is GET and POST.  But HTTP has many other verbs, and we'll use most of them in this article series (GET, POST, PUT, and DELETE for now, although there are others), REST gives us a framework for using those verbs to make changes, or view the properties of things on the web.

They generally do what they sound like:

GET - get information (generally read-only)
POST - create a new object (or modify an existing object repeatedly)
PUT - modify an object idempotently so that multiple PUTs will result in the same state
DELETE - delete an object

This is all very abstract, so let's come up with an extremely contrived example: imagine a barn full of goats ( yes, my first job was as a farmhand ).

Let's say that you had a robot that you wanted to perform various tasks relating to this barn full of goats.  Maybe the first one would be a survey of all the goats in the barn.

If the robot spoke REST, then you might send a text message to your robot that looked like this:

GET /barn/1/goats

Because the robot knows that in REST, that means that you want to know about all the goats in barn 1, your robot would trundle off (or fly, or crawl) to barn 1, and might come back with this data:

goat 1: 
    name: Dopey
goat 2: 
    name: Speedy 

Maybe then you wanted to know more about Speedy, so you'd text your robot this:

GET /barn/1/goats/2 

and your robot would gather up some more information about goat 2:

goat 2: 
    name  : Speedy
    eats  : Himalayan Blackberry
    hates : Dopey 

Okay, so what the hell do goats and barns have to do with iHealth?  Well, if we substitute in QKViews for goats, we can start to see some information about our data in the same way that we were able to examine our herds of goats:

GET /qkview-analyzer/api/qkviews 

Will show us a list of the qkviews that we have in our account:

This is a sample, and there is a special QKView that isn't show in the listing, but that you should always have in your account, a QKView with an ID of 0.  It's a sample QKView that we allow everyone access to in order to see how iHealth works with requireing you to upload anything of your own.

So let's pick QKView 0 and load it up.  We'll see some details about that QKView:

GET /qkview-analyzer/api/qkviews/0

Feel free to poke around.  At the bottom of the listing are some "discovery" URLs.  Load them up in your browser; there is a ton to explore here, and you can get an idea of the kind of data you can work with without writing a single line of code.  Code will come later, as you'll need it for things like adding to your QKView collections, and modifying existing QKView entries, which are tricky to do with just a browser.