Recent updates in API


Date In short Details To be done
Feb 7, 2016 DELETE transaction method added Added method "DELETE" for transaction. Which sets transaction's attribue "deleted" = true.
  • Update deocumentation

For questions pleae mail us: litaninm[at]gmail.com

Key

Each operation with transactions require you to provide key as identification of workspace. Following operations allowed with keys:
  • GET key. Response is newly created key identificator.

GET key

curl http://obsly.com/api/v1/key

                    {
                        "user_id":null,
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg="
                    }

Request

No params.

Response

user_id User ID for the key, for private(protected) keys.
key Key identificator. To be used for transaction operations.

GET existing key

curl http://obsly.com/api/v1/key/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=

                    {
                        "user_id":null,
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg="
                    }

Request

No params.

Response

user_id User ID for the key, for private(protected) keys.
key Key identificator. To be used for transaction operations.

Accounts

Accounts are used as basic storage of balances. Following operations allowed with accounts:
  • POST account. Create new account.
  • GET account list. Response is an array of accounts within the provided workspace (key).
  • GET account by ID. Response is a account found by specified ID.
  • PUT account. Change account details.
  • DELETE account. Mark account as "deleted".

POST account

curl --data '{"key": "LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=", "name": "default", "currency": "USD", "start_amt": 0, "sign": "$"}'  http://obsly/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/accounts

                    {
                        "_id":"5651937890d2d35346000004",
                        "datetime_added":"2015-11-22T18:05:44.415+08:00",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "name":"default",
                        "currency":"USD",
                        "start_amt":0,
                        "sign":"$"
                    }

Request

param required description
key * Key, which identifies the workspace to create an account in
name * Account name, which will be shown in the reports
currency * Account currency, may be one of the known reserved currencies or your own, custom currency. For the known currencies, currency rate could be taken automatically for cross-currency operations and reports. For your own defined currency, you will have to provide the currency rate in case of cross-currency operations or reports
start_amt Start balance for the account. Instead of creating a new transaction to equalize the current account balance, you may set it as start_amt. The difference is in reporting, new transaction will be displayed in the transaction and money flow reporting, start_amt will not
sign Currency short sign, like for USD it is set to '$' by default

Response

Response is newly created Account entity object:
param required description
_id * ID of the account
datetime_added * Date time when the account was created
key * Key (workspace) account belongs to
name * Account name
currency * Acocunt currency
start_amt * Account start amount. 0 if not set
sign * Account currency sign. Empty string if not set

GET account list

Template:
curl http://obsly.com/api/v1/{key}/accounts
Sample:
curl http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/accounts

                    [
                        {
                            "_id":"565190f890d2d35197000004",
                            "datetime_added":"2015-11-22T17:55:04.745+08:00",
                            "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                            "name":"default1",
                            "currency":"USD",
                            "start_amt":0,
                            "sign":"$"
                        },
                        {
                            "_id":"5651933b90d2d35307000004",
                            "datetime_added":"2015-11-22T18:04:43.336+08:00",
                            "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                            "name":"default2",
                            "currency":"EUR",
                            "start_amt":0,
                            "sign":"$"
                        }
                    ]

Request

param required description
load_amount Load account amount as of now
per_page * Number of transactions per page
page * Page number to show

Response

Array of Account entity objects (see details above).

GET account by ID

Template:
curl http://obsly.com/api/v1/{key}/accounts/{id}
Sample:
curl http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/accounts/565190f890d2d35197000004

                    {
                        "_id":"565190f890d2d35197000004",
                        "datetime_added":"2015-11-22T17:55:04.745+08:00",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "name":"default",
                        "currency":"USD",
                        "start_amt":0,
                        "sign":"$"
                    }
                    

Request

No params.

Response

Account entity objects (see details above).

PUT account

Template:
curl -X PUT -d '{JSON}' http://obsly.com/api/v1/{key}/accounts/{id}
Sample:
curl -H 'Content-Type: application/json' -X PUT -d '{"name": "My USD Account"}' http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/accounts/565190f890d2d35197000004

                    {
                        "_id":"565190f890d2d35197000004",
                        "datetime_added":"2015-11-22T17:55:04.745+08:00",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "name":"My USD Account",
                        "currency":"USD",
                        "start_amt":0,
                        "sign":"$"
                    }
                    

Request

No params.

Response

Updated Account entity object (see details above).

DELETE account

Template:
curl -X DELETE  http://obsly.com/api/v1/{key}/accounts/{id}
Sample:
curl -X DELETE  http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/accounts/565190f890d2d35197000004

                    {
                        "_id":"565190f890d2d35197000004",
                        "datetime_added":"2015-11-22T17:55:04.745+08:00",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "name":"My USD Account",
                        "currency":"USD",
                        "start_amt":0,
                        "sign":"$"
                    }
                    

Request

No params.

Response

Removed Account entity object (see details above).

Transactions

Transaction requests used to apply changes to account balances. Following operations allowed with transactions:
  • POST transaction. Create new transaction.
  • GET transaction list. Response is an array of transactions within the provided workspace (key).
  • GET transaction by ID. Response is a transaction found by specified ID.
  • PUT transaction. Change transaction details.
  • DELETE transaction. Mark transaction as "deleted".

POST transaction

Template:
curl --data '{JSON}'  http://obsly.com/api/v1/{key}/transactions
Sample:
curl --data '{"key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=","account_id":"565190f890d2d35197000004","label_list":["test"],"currency":"USD","amt":-100,"note":"just to test"}'  http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/transactions

                    {
                        "_id":"5655e10490d2d36976000004",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "datetime_added":"2015-11-25T23:25:40.344+07:00",
                        "datetime_on":"2015-11-25T23:25:40.344+07:00",
                        "account_id":"565190f890d2d35197000004",
                        "label_list":["test"],
                        "currency":"USD",
                        "rate":1,
                        "amt":-100,
                        "note":"just to test",
                        "account":
                            {
                                "_id":"565190f890d2d35197000004",
                                "datetime_added":"2015-11-22T16:55:04.745+07:00",
                                "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                                "name":"My USD Account",
                                "currency":"USD",
                                "start_amt":0,
                                "sign":"$"
                            }
                    }

Request

Request is new Transaction entity object details:
param required description
key * Key (workspace) transaction belongs to
datetime_on Effective datetime of transaction
account_id * Account id, transaction changes the balance of
label_list * List of labels for transaction. Used for reporting
currency Transaction currency. If not set, account currency taken
amt * Amount of the transaction. Could be negative as sign of account debiting, and positive as account crediting
rate Rate if transaction currency is different from the account currency
note Optional parameter for transaction notes

Response

Response is newly created Transaction entity object:
param required description
_id * ID of the transaction
key * Transacton key (workspace)
datetime_added * Date time when the transaction was created
datetime_on * Effective date time of transaction
account_id * Transaction account ID
label_list * Transaction labels
currency * Acocunt currency
rate Transaction rate (when transaction currency and account currency are different)
amt * Transaction amount
note Transaction notes

GET transaction list

Template:
curl http://obsly.com/api/v1/{key}/transactions
Sample:
curl http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/transactions

                    [
                        {
                            "_id":"5655e10490d2d36976000004",
                            "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                            "datetime_added":"2015-11-25T23:25:40.344+07:00",
                            "datetime_on":"2015-11-25T23:25:40.344+07:00",
                            "account_id":"565190f890d2d35197000004",
                            "label_list":["test"],
                            "currency":"USD",
                            "rate":1,
                            "amt":-100,
                            "note":"just to test",
                            "account":
                                {
                                    "_id":
                                        "565190f890d2d35197000004",
                                        "datetime_added":"2015-11-22T16:55:04.745+07:00",
                                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                                        "name":"My USD Account",
                                        "currency":"USD",
                                        "start_amt":0,
                                        "sign":"$"
                                }
                        }
                    ]

Request

param required description
per_page * Number of transactions per page
page * Page number to show

Response

Array of Transaction entity objects (see details above).

GET transaction by ID

Template:
curl http://obsly.com/api/v1/{key}/transactions/{id}
Sample:
curl http://obsly.com/api/v1/transactions/5655e10490d2d36976000004

                    {
                        "_id":"5655e10490d2d36976000004",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "datetime_added":"2015-11-25T23:25:40.344+07:00",
                        "datetime_on":"2015-11-25T23:25:40.344+07:00",
                        "account_id":"565190f890d2d35197000004",
                        "label_list":["test"],
                        "currency":"USD",
                        "rate":1,
                        "amt":-100,
                        "note":"just to test",
                        "account":
                            {
                                "_id":"565190f890d2d35197000004",
                                "datetime_added":"2015-11-22T16:55:04.745+07:00",
                                "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                                "name":"My USD Account",
                                "currency":"USD",
                                "start_amt":0,
                                "sign":"$"
                            }
                    }

Request

No params.

Response

Requested transaction entity (see details above).

PUT transaction

Only Transaction note could be changed with PUT method. All other transaction criterias are not changable by default to prevent reporting mismatch.
Template:
curl -X PUT -d '{JSON}' http://obsly.com/api/v1/{key}/transactions/{id}
Sample:
curl -H 'Content-Type: application/json' -X PUT -d '{"note": "Note changed"}' http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/transactions/5655e10490d2d36976000004

                    {
                        "_id":"5655e10490d2d36976000004",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "datetime_added":"2015-11-25T23:25:40.344+07:00",
                        "datetime_on":"2015-11-25T23:25:40.344+07:00",
                        "account_id":"565190f890d2d35197000004",
                        "label_list":["test"],
                        "currency":"USD",
                        "rate":1,
                        "amt":-100,
                        "note":"Note changed",
                        "account":
                            {
                                "_id":"565190f890d2d35197000004",
                                "datetime_added":"2015-11-22T16:55:04.745+07:00",
                                "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                                "name":"My USD Account",
                                "currency":"USD",
                                "start_amt":0,
                                "sign":"$"
                            }
                    }

Request

No params.

Response

Updated Transaction entity object (see details above).

DELETE transaction

Template:
curl -X DELETE  http://obsly.com/api/v1/{key}/transactions/{id}
Sample:
curl -X DELETE  http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/transactions/5655e10490d2d36976000004

                    {
                        "_id":"5655e10490d2d36976000004",
                        "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                        "datetime_added":"2015-11-25T23:25:40.344+07:00",
                        "datetime_on":"2015-11-25T23:25:40.344+07:00",
                        "account_id":"565190f890d2d35197000004",
                        "label_list":["test"],
                        "currency":"USD",
                        "rate":1,
                        "amt":-100,
                        "note":"Note changed",
                        "account":
                            {
                                "_id":"565190f890d2d35197000004",
                                "datetime_added":"2015-11-22T16:55:04.745+07:00",
                                "key":"LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=",
                                "name":"My USD Account",
                                "currency":"USD",
                                "start_amt":0,
                                "sign":"$"
                            }
                    }

Request

No params.

Response

Removed Transaction entity object (see details above).

Labels

Labels are used to add the context to transaction. Multiple labels could be applied. Following operations allowed with labels:
  • GET label list. Response is an array of labels within the provided workspace (key).
Label entity is being automatically created once it is appeared in new transaction. Labels with no transactions related to them do not make sense, thats why we don't allow to create labels with POST.

Removing label doesn't make sense, since in case there are still labeled transactions, you may lose track over them. So removing all transactions with specific label will automatically remove the label itself.

GET label list

Template:
curl http://obsly.com/api/v1/{key}/labels
Sample:
curl http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=/labels

                    [
                        {
                            "label":"test",
                            "n":2
                        },
                        {
                            "label":"test2",
                            "n":1
                        }
                    ]

Request

param required description
load_amount Load label amount as of now
per_page * Number of transactions per page
page * Page number to show

Response

Response is array of labels with number of times the label appears in transactions:
param required description
label * Label name
n * Number of times the label appeared in transactions

Aggregate

Aggregation end point:
  • GET aggregated amount.

GET key

curl http://obsly.com/api/v1/LfGGp2sJD2uK1mKjXAQJig-BvmbnHI0K4RmFC9_wEIg=

                    {
                        ???
                    }

Request

param required description
label Array of labels limited for aggregation
account_id Array of account IDs limited for aggregation

Response

???
OBSLY API v1 documentation.