We've created the Kanbanery API to allow you to easily integrate your systems and applications with Kanbanery. With this API you can manage your resources like a project's tasks, columns, task comments/subtasks/issues and more.
How does it work?
The Kanbanery API is implemented as a REST interface for the resources mentioned above. If you're not familiar with REST see more information about REST.
Basically, to get or update something in your project(s) you'll make an HTTP request with some data and receive JSON data in the response. Different API calls use different HTTP verbs like GET, POST, PUT and DELETE.
Before you start implementing your integration with Kanbanery you can get familiar with our API and its responses by using the curl command in your shell:
You can do many things with the Kanbanery API. Possibilities are unlimited and here a few ideas for you:
You can build a custom Kanbanery client for your favourite smartphone or system platform (or even a desktop GUI app!),
Your SCM post-commit hooks can automatically resolve an issue assigned to some task when a commit message matches the issue or even move this task to the next column,
Your server monitoring scripts can automatically add a task to remind you about some sysadmin work.
In Kanbanery every user already has their own, unique API token. The token is just a string containing alphanumerical characters. If you use your project's RSS feed for monitoring what's happening in the project you already use this token.
In order to use the Kanbanery API you need to know your API token. You can find it under the "API Token" tab on your user account settings page or you can use basic authentication for retrive user information, where you would find api_token.
Once you know your token you can use it to authenticate your requests. There are 2 ways to do this:
Note, when you use our API we identify your user account by this token. In other words, all API activity will be seen as your activity and other project members will see you as the author of any changes.
Note, this method is not recommended, but it can be used for getting api_token from user resource.
As mentioned in the previous section, API calls are made on behalf of one of your project members. This means that the role of this member is being checked when you make API calls. Roles define what you can do and what you cannot do. Currently there are 3 roles in Kanbanery: project viewer (read only user), project member and project manager. You can change a user's role in a specific project on the "Project members" page.
Note that if your paying plan allows you to add one more additional members to the project then you can dedicate this new user account for your API needs. Just set its name to "API", "R2D2", "C3PO" or whatever you want and assign it some nice avatar (at gravatar.com) to distinguish it from "real" users on the board.
URL - Protocol, domain and path
Here is an example of the URL for getting column information:
First, the protocol. Kanbanery uses a secure http connection (https) for almost everything to keep your project data safe from sniffing. Thus you should use https protocol for all API calls.
Second, the domain. All API calls should be using your workspace's subdomain in kanbanery.com. In the above example your workspace's domain is WORKSPACE.kanbanery.com. To find it, just open your browser and go to your project's Kanban board - the domain shown in your browser's location bar is the one you should use.
Third, the path. All paths should start with /api/v1, as this is the first and only version of our API for now. When we decide to change the API in future and its release includes non-backwards compatible changes we'll put it at /api/v2. This way, your clients (read: systems and applications integrated with Kanbanery) will still work and you'll have time to update them to use the new API. The rest of the path describes names and identifiers of resources you want to act on.
All resources available in Kanbanery API are described in detail in following sections of this document.
Response format and statuses
Kanbanery API supports one response format: JSON. Specifying the format by appending the ".json" to the request URL is optional.
For "create" and "update" requests the response body contains resource data serialized in JSON.
If the request succeeds the returned status will be 200 (OK), except for requests that create resources, for which the status will be 201 (Created).
If the API token is invalid or is missing the API returns 401 (Unauthorized) HTTP status.
If the role assigned to user accessing the API doesn't allow them to perform the requested action upon the requested resource the API returns 403 (Forbidden) HTTP status.
If you're trying to create or modify any resource and some parameters have invalid values or some required parameters are missing the API returns 422 (Unprocessable entity) HTTP status and error description in JSON.
If a resource removal (DELETE) request fails for some reason the API will return 409 (Conflict) HTTP status.
Request data format
When creating or updating resources through our API you need to specify resource attributes as form-encoded data. These attributes should be put inside a hash map that should be named after resource. For example, to update task title and position the data should look like this:
The column must not contain any tasks (must be empty) in order to be removable. You need to delete all of a column's tasks or move them to another column before you can delete a column. If you want to remove a column and move its tasks to other column at once just settask[column_id] parameter to id of column to which tasks should be sent to. For example: