API

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. In further commands, we'll be calling it $COOKIE.

You can quickly get a cookie by running the following command. Be sure to put in your email address and password.

curl -is -F 'J:A-login=BTDT::Action::Login' -F 'J:A:F-address-login=EMAILADDRESS' -F 'J:A:F-password-login=PASSWORD' http://hiveminder.com/splash | grep -o 'JIFTY_SID_HIVEMINDER=[0-9a-f]\+'

Creating a Task

The Request

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:

curl
The name of the program
-b JIFTY_SID_HIVEMINDER=$COOKIE
How you tell curl what your cookie is, for authentication
-F summary="hello from curl"
How you tell curl the arguments to this task creation
http://hiveminder.com/=/model/Task.yml
The URL of the request. The .yml indicates we want our result in YAML, we could also pick .xml, .json, and even .pl.

The Response

If all goes well, you'll get the following response (in YAML just as we requested):

---
action_class: BTDT::Action::CreateTask
content:
    id: 271901
    record_locator: ACJX
error: ~
failure: 0
field_errors: {}
field_warnings: {}
message: Your task has been created!
success: 1

Let's examine some of these fields:

action_class: BTDT::Action::CreateTask
The action that the server ran. You can ignore this one.
id: 271901
The numeric ID of the created task.
record_locator: ACJX
The human-friendly version of the task ID. This is what we display as the task ID in the web interface and elsewhere. This is because #ACJX is a lot easier to remember. We use the Number::RecordLocator Perl module to convert between the actual numeric ID and the friendlier record locator.
error: ~
In YAML, a tilde represents no value. So there were no errors.
field_errors: {} and field_warnings: {}
These are (empty) mappings of column name to validation and canonicalization notices. For example, if you give a due date of "tomorrow" then field_warnings will be due: 2014-10-23 to tell you that it canonicalized the value you gave it. You can ignore these.

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.

Generic CRUD

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

Actions

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.

Search

We have a number of ways to let you search through your tasks:

/=/action/BTDT.Action.TaskSearch
Token-based search for tasks. Practically every time you have a tasklist in the web interface, you're using this action.
/=/action/BTDT.Action.DispatchQuicksearch
A text-based search that looks through your tasks' summaries, descriptions, and tags
/=/action/BTDT.Action.SearchTask
A generic action for searching for basic column values
/=/model/BTDT.Model.Task/column
List all the values of column for tasks you can see
/=/model/BTDT.Model.Task/column/value
A "search" for one column-value pair. You'll only get one result, so it's recommended you use this when you know your column is unique.
/=/search/BTDT.Model.Task/column1/value1/column2/value2
A search for column-value pairs. Can return multiple values.

Except for the first two, these are available for all models, not just Tasks.

Discoverability

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