Hiveminder has a simple, yet powerful API. Like the rest of our application, we try to give you the building blocks to use Hiveminder however suits you best.
You can see the very terse description of the API at http://hiveminder.com/=/help. This document is more of a walkthrough to how it all works, and how you can use it.
We also have a mailing list for discussing Hiveminder's API and what people are doing with it. Join us!
If you speak Perl, we have a ready-made Net::Hiveminder to ease working with our API.
Our API assumes that you're logged in (or using OAuth) Logged in users have a cookie, JIFTY_SID_HIVEMINDER. You'll need to send this cookie with every request, so we know who you are.
To play around, we'll use the curl command line utility. It makes this kind of interaction easy. You'll also need your JIFTY_SID_HIVEMINDER cookie. Your web browser should have it available. In further commands, we'll be calling it $COOKIE.
curl -b JIFTY_SID_HIVEMINDER=$COOKIE -F summary="hello from curl" http://hiveminder.com/=/model/Task.yml
There are a few pieces to this. Here's what each one means:
If all goes well, you'll get the following response (in YAML just as we requested):
---
action_class: BTDT::Action::CreateTask
content:
id: 271901
error: ~
failure: 0
field_errors: {}
field_warnings: {}
message: Your task has been created!
success: 1
Let's examine some of these fields:
In addition to getting a response, we also get some special values in the HTTP response header. Namely, Hiveminder gives response code 302 to indicate redirection. We also get Location: http://hiveminder.com/=/model/BTDT%3A%3AModel%3A%3ATask/id/271901 (the redirection's target URL) to tell you how to read the newly created object. So if you're using a library in your favorite programming language, you may instead see the task itself, instead of the create action's results.
Hiveminder's API lets you create, read, update, and delete things (as long as you have permission to do it). It's not limited to just tasks either; you can create groups, delete IM accounts, and so on. Using our API, you can do everything that our other interfaces do, and more.
We make use of different HTTP request methods. You're probably familiar with GET and POST. We use GET for reading objects and POST for creating them. We also use PUT for update and DELETE for delete. Here are examples of using curl for each of these.
Create a new task: curl -F summary=hello -b JIFTY_SID_HIVEMINDER=$COOKIE http://hiveminder.com/=/model/Task.yml
Read task 271901: curl -b JIFTY_SID_HIVEMINDER=$COOKIE http://hiveminder.com/=/model/Task/id/271901.yml
Update task 271901's due date: curl -X PUT -F due=tomorrow -b JIFTY_SID_HIVEMINDER=$COOKIE http://hiveminder.com/=/model/Task/id/271901.yml
Delete task 271901: curl -X DELETE -b JIFTY_SID_HIVEMINDER=$COOKIE http://hiveminder.com/=/model/Task/id/271901.yml
In addition to CRUD, we also expose our actions. Actions are like functions: each takes arguments, does its thing, then returns values. We have a wide range of actions, from CRUD, to braindump, even upgrading to Pro.
Let's have a look at our braindump action, ParseTasksMagically. It takes two arguments. The first, "text", you're already familiar with: it's the text you submit that eventually becomes tasks.
The second argument is "tokens", which we don't expose in the web interface. Every tasklist has a list of tokens associated with it, things like "due before today", "owner me", and "tag music". This token list is the tasklist's identity; when you export tasks to a text file, or get an Atom feed of the tasklist, tokens are what is saved. Anyway, you can pass in tokens to this argument to set attributes for all of the created tasks at once.
Let's say we want to braindump the following text:
finish documenting API [hiveminder]
just need to think of a good example braindump
profit!
We also want to apply the following tokens to these tasks, namely "tag @work". So after URI-encoding everything, we end up with this (lines broken for clarity):
curl
-F text='finish documenting API [hiveminder]
just need to think of a good example braindump
profit!'
-F tokens='tag @work'
-b JIFTY_SID_HIVEMINDER=$COOKIE
http://hiveminder.com/=/action/ParseTasksMagically.yml
You'll get back a lot of text. Among other things, you'll see fields called "completed", "create_failed", "update_failed", and "updated". These are there because ParseTasksMagically is actually a specialization of UploadTasks, so you can ignore these fields. It's hopefully mostly obvious what the rest of it means.
We have a number of ways to let you search through your tasks:
Except for the first two, these are available for all models, not just Tasks.
We've tried to make our API discoverable. If you want to know what arguments an action takes, or what columns a model has, you can easily figure that out.
If you want to know what arguments the UploadTasks action takes, you can get that information with:
curl http://hiveminder.com/=/action/UploadTasks.yml
If you want to know what columns a Task has:
curl http://hiveminder.com/=/model/Task.yml