API

Overview

This API is accessed using normal HTTP requests with parameters passed as a query string, both POST and GET will work. All responses are in JSON format encoded with UTF-8.

The API is accessed through the following URL:

http://api.kassabok.nu/current

Authentication

The authentication method is basic HTTP-Auth, where the username is the email address associated with the account being accessed.

Common parameters

Name Type Description
function string Name of the function to call. See what functions are available below.
version int Optional. Defaults to 1.

Error handling

Any errors, caused by input validation, permissions, system errors etc are reported like this:

{"error":{"status":-1,"message":"System error."}}

I.e. at least status and message fields are contained in an error wrapper. Status code -1 means undefined error. -5 means permission denied.

Available functions

get-categories (v1)

Fetch a list of categories available to a user filtered by category type; income or expense.

Parameters

Name Type Mandatory Description
function string Yes Set to "get-categories".
version int Set to 1.
type string Yes Type of transaction to get categories of, accepted values are "income" and "expense".

Response

[
{"id":"1279","name":"Kategori 1"},
{"id":"1278","name":"Kategori 2"},
{"id":"1277","name":"Kategori 3"}
]
id int Globally unique category id.
name string User defined name of the category.

get-all-categories (v1)

Fetch a complete list of categories available to a user regardless of transaction type. This method saves bandwidth because it groups category types in chunks.

Parameters

Name Type Mandatory Description
function string Yes Set to "get-all-categories".
version int Set to 1.

Response

{"expense":
[
{"id":"1279","name":"Expense category 1"},
{"id":"1278","name":"Expense category 2"},
{"id":"1277","name":"Expense category 3"}
],
{"income":
[
{"id":"1279","name":"Income category 1"},
{"id":"1278","name":"Income category 2"},
{"id":"1277","name":"Income category 3"}
]}
id int Globally unique category id.
name string User defined name of the category.

add-transaction

Add a transaction to a users transaction book (kassabok).

Parameters

Name Type Mandatory Description
function string Yes Set to "add-transaction".
version int Set to 1.
type string Yes Type of transaction, accepted values are "income" and "expense".
category int Yes Category id to attach transaction to.
amount amount Yes Unsigned integer that represents an amount in cents (ören), i.e. 70,50 SEK becomes 7050.
date date Yes Date the transaction occured, must be a valid date in format YYYY-MM-DD.
description string Optional user defined description of the transaction.

Response

{"success":true}