Introduction

The ActiveBudget API is provided by the Ruby on Rails REST interface. It is simply XML over HTTP with an emphasis on HTTP verbs (GET, POST, PUT & DELETE).

ActiveBudget will return XML on any resource request that asks for XML as the reply. Alternatively, you can append most urls with .xml to see its XML. For example, http://activebudget.org/jobs.xml will render an XML representation of the jobs for a user.

The best way to begin interacting with the API is through the curl command. To return a list of jobs using curl, you can use

curl -u 123456:X http://activebudget.org/jobs.xml

Which will return XML because of the .xml extension. You can also request XML in header like so:

curl -u 123456:X -H 'Content-Type: application/xml' http://activebudget.org/jobs

Authentication

ActiveBudget uses HTTP Basic Authentication. Your username is the email address you use to login. In the examples above you would need to replace -u 123456:X with the credentials for your account.

Resource Basics

There are 5 basic actions on any resource.

Handling Errors

ActiveBudget Resources

Category

The category for an item.

Required Fields

• Name

Example XML

<category>
  <id type="integer">1</id>
  <name>Food</name>
</category>

Item

A transaction, either positive or negative.

Required Fields

• Value - Assumed negative if + or - is not specified. Cannot be zero
• Date

Example XML

<item>
  <date type="date">2007-01-01</date>
  <description>Burrito</description>
  <id type="integer">1</id>
  <value type="integer">-6</value>
  <category>
    <id type="integer">1</id>
    <name>Food</name>
  </category>
</item>

Additional Parameters

The index method will only return 50 items at a time. You may pass offset to retrieve more items. You may also pass on to get the items on a particular day.

  # GET /items.xml
  # GET /items.xml?&offset=50
  # GET /items.xml?&on=20070101
  # GET /items.xml?&on=20070101&offest=50

Job

A job

Required Fields

• Name
• Hourly Rate

Example XML

<job>
  <active type="boolean">true</active>
  <id type="integer">1</id>
  <name>Hacking</name>
<rate type="decimal">100.0</rate>
</job>

Paycheck

Paychecks belong to a job, so they are accessed as such. For example /jobs/1/paychecks/2. The item_id attribute represents the transaction that paid the paycheck.

Required Fields

• Job
• Value

Example XML

<paycheck>
  <created-at type="datetime">2007-02-01T00:00:00Z</created-at>
  <description>January Invoice</description>
  <id type="integer">1</id>
  <item-id type="integer">1</item-id>
  <value type="decimal">100.0</value>
</paycheck>

Additional Parameters

The index method will only return 50 items at a time. You may pass offset to retrieve more items.

Recurring

If an item reoccurs on the same day every month, a Recurring may be created to automate create. The lib/recur.rb script runs once a day and creates an item for each recurring scheduled on that day.

Required Fields

• user_id
• Value
• Day - the day of the month to be run. Currently accepts values 1-28

Example XML

<recurring>
  <day type="integer">1</day>
  <description>Rent</description>
  <id type="integer">1</id>
  <value type="integer">-500</value>
  <category>
    <id type="integer">1</id>
    <name>Rent</name>
  </category>
</recurring>

Task

A unit of work done for a job. Measured in minutes. When a task has a paycheck_id, it represents that it in the process of being paid for.

Required Fields

• job_id
• Date
• Minutes - cannot be 0

Example XML

<task>
  <date type="date">2007-01-01</date>
  <description>Did some work</description>
  <id type="integer">1</id>
  <job-id type="integer">1</job-id>
  <minutes type="integer">60</minutes>
  <paycheck-id type="integer">1</paycheck-id>
</task>

Additional Parameters

The index method will only return 50 items at a time. You may pass offset to retrieve more items. You may also pass on to get the items on a particular day. To get the tasks on a particular job, pass the job_id parameter.

  # GET /tasks.xml
  # GET /tasks.xml?&offset=50
  # GET /tasks.xml?&on=20070101
  # GET /tasks.xml?&on=20070101&offest=50
  # GET /tasks.xml?&job_id=1
  # GET /tasks.xml?&job_id=1&on=20070101
  # GET /tasks.xml?&job_id=1&on=20070101&offset=50