It is always nice to see some simple examples without having to really understand all the little details.
Our first example is designed to give you a sense of what’s possible. We are going to use “curl” here as a simple and widely available tool to access the API from a command line. If you want to get and find out a little about curl then please read A little curl housekeeping.
$ curl http://api.ivyroot.com/api.json.1/measures
$
Hmm not very impressive, did we mention authorization? Let’s try again with some credentials:
$ curl -u alice:password http://api.ivyroot.com/api.json.1/measures
[{"id":6,"user":"alice"},{"id":7,"user":"alice"},{"id":8,"user":"alice"},
{"id":9,"user":"alice"},{"id":10,"user":"alice"}]
Success! A reply, albeit a slightly minimal one.
Let’s look at that URL. Understanding the structure of IvyRoot URLs is key to understanding the API. We’ll break it down into three basic parts:
All IvyRoot API requests contain at least these three elements. The hostname is pretty obvious and we won’t discuss that further. The next section indicates that we wish to access the API instead of the main web UI. In this example we’re saying that we want JSON responses and the .1 indicates that we want the minimal information in the response. We can specify any number in the range of 0 to 9 with 9 always being the most verbose response we can get. Not specifying the verbosity leaves the API to choose a suitable level.
If we want a really quiet response, for example when we don’t actually need any reply data when we’re uploading data, then we can use “api.quiet” or “api.0”.
The next part of the URL deals with which aspect of IvyRoot we want to work with. In this case it’s measures. Measures are where IvyRoot stores all the data points and many of your dealings with the API will be to read and manipulate measures.
Let’s look a little further at that last example:
$ curl -u alice:password http://api.ivyroot.com/api.json.1/measures
[{"id":6,"user":"alice"},{"id":7,"user":"alice"},{"id":8,"user":"alice"},
{"id":9,"user":"alice"},{"id":10,"user":"alice"}]
We can see that we’ve got a list of id’s and user for each measure that we’re allowed to see. Try and see what happens when we skip specifying the detail and get the API to judge what it thinks is the level of detail we’re likely to need.
$ curl -u alice:password http://api.ivyroot.com/api.json/measures
You can also try with api.json.100 the output of which will show the impact of the detail level. You can read more about the detail level in the ‘API verbosity section’.
If you’d like to read a little bit about setting up CURL then read A little curl housekeeping. Experienced users can skip ahead and read Looking at measures