README.rdoc in freeagent_api-0.1.0 vs README.rdoc in freeagent_api-0.2.0

- old
+ new

@@ -1,62 +1,234 @@ = freeagent_api -Simple Ruby interface to the Freeagent Central API (http://www.freeagentcentral.com/developers/freeagent-api). +Simple ActiveResource Ruby wrapper for the Freeagent Central API (http://www.freeagentcentral.com/developers/freeagent-api). -This is an early development version of a Ruby wrapper for the Freeagent API. Currently this only supports GET requests (POST will follow shortly) and only the following API methods are supported (more will follow): +This supports all GET, POST, PUT and DELETE ActiveResource calls for the following API resources: +* Company * Contacts -* Invoices -* Invoice items * Projects * Tasks +* Invoices +* Invoice Items * Timeslips -There is no test suite yet. If you feel brave, then feel free to clone, fork and play around. +At the moment, the following API resources are NOT supported (although is being worked on): +* Users +* Expenses +* Attachments + +Feel free to clone, fork and add tests. + == Installation To install as a Gem, just run: $ sudo gem install freeagent_api -s http://gemcutter.org +Please note: version 0.2 is significantly different from 0.1 so if you are upgrading from the early development version please re-familiarise yourself with the documentation. + == Usage === Authentication - Freeagent.domain = 'yourdomain.freeagentcentral.com' - Freeagent.username = 'your@login.com' - Freeagent.password = 'your_password' + Freeagent.authenticate({ + :domain => 'yourdomain.freeagentcentral.com', + :username => 'your@login.com', + :password => 'your_password'}) +=== Company + +<b>Timelines</b> + + @invoice_timeline = Company.invoice_timeline + @tax_timeline = Company.tax_timeline + === Contacts - @contacts = Contact.find_all # returns all contacts - @contact = Contact.find(contact_id) # returns specific contact +<b>Find contacts</b> -=== Invoice + @contacts = Contact.find :all # returns all contacts + @contact = Contact.find id # returns specific contact - @invoices = Invoice.find_all # returns all invoices - @invoices = Invoice.find_all(project_id) # returns all invoices for project - @invoice = Invoice.find(invoice_id) # returns specific invoice +<b>Create contact</b> -=== Invoice items + # Required attributes + # :first_name + # :last_name + + @contact = Contact.new params + @contact.save - @items = InvoiceItem.find_all(invoice_id) # returns all items for invoice +<b>Update contact</b> + @contact.first_name = 'Joe' + @contact.save + +<b>Delete contact</b> + + Contact.delete id + # or + @contact.destroy + === Projects - @projects = Project.find_all # returns all projects - @project = Project.find(project_id) # returns specific project +<b>Find projects</b> + @projects = Project.find :all # returns all projects + @project = Project.find id # returns specific project + +<b>Create project</b> + + # Required attribues + # :contact_id + # :name + # :payment_term_in_days + # :billing_basis # must be 1, 7, 7.5, or 8 + # :budget_units # must be Hours, Days, or Monetary + # :status # must be Active or Completed + + @project = Project.new params + @project.save + +<b>Update project</b> + + @project.name = 'Web design project' + @project.save + +<b>Delete project</b> + + Project.delete id + # or + @project.destroy + +<b>Nested resources</b> + + @invoices = @project.invoices + @timeslips = @project.timeslips + === Tasks - @task = Task.find(project_id, task_id) # returns specific task for project +<b>Find tasks</b> + @tasks = Task.find :all # returns all tasks + @task = Task.find id # returns specific task + +<b>Create task</b> + + # Required attributes + # :name + + @task = Task.new params + @task.save + +<b>Update task</b> + + @task.name = 'Create wireframes' + @task.save + +<b>Delete task</b> + + Task.delete id + # or + @task.destroy + +=== Invoices + +<b>Find Invoices</b> + + @invoices = Invoice.find :all # returns all invoices + @invoice = Invoice.find id # returns specific invoice + +<b>Create invoice</b> + + # Required attributes + # :contact_id + # :project_id + # :dated_on + # :reference + # :status + + @invoice = Invoice.new params + @invoice.save + +<b>Update invoice</b> + + @invoice.status = 'Sent' + @invoice.save + +<b>Delete invoice</b> + + Invoice.delete id + # or + @invoice.destroy + +<b>Changing status</b> + + @invoice.mark_as_draft + @invoice.mark_as_sent + @invoice.mark_as_cancelled + +=== Invoice items + +<b>Find invoice items</b> + + @invoice_items = InvoiceItem.find :all # returns all invoice items + @invoice_item = InvoiceItem.find id # returns specific invoice item + +<b>Create invoice item</b> + + # Required attributes + # :item_type # must be Hours, Days, Months, Years, Products, Services, Expenses, Discount, Credit, Comment + # :description + # :quantity + # :price + # :sales_tax_rate + + @invoice_item = InvoiceItem.new params + @invoice_item.save + +<b>Update invoice item</b> + + @invoice_item.name = 'Create wireframes' + @invoice_item.save + +<b>Delete invoice item</b> + + InvoiceItem.delete id + # or + @invoice_item.destroy + === Timeslips - @timeslips = Timeslip.find_all # returns all timeslips - @timeslips = Timeslip.find_all(project_id) # returns all timeslips for project - @timeslip = Timeslip.find(timeslip_id) # returns specific timeslip +<b>Find timeslips</b> + + @timeslips = Timeslip.find :all, :params => {:from => '2009-10-01', :to => '2009-10-30'} + # returns all timeslips (:from and :to dates required) + @timeslip = Timeslip.find id # returns specific timeslip + +<b>Create timeslip</b> + + # Required attributes + # :user_id + # :hours + # :dated_on + # :task_id OR :new_task + + @timeslip = Timeslip.new params + @timeslip.save + +<b>Update timeslip</b> + + @timeslip.hours = '3.5' + @timeslip.save + +<b>Delete timeslip</b> + + Timeslip.delete id + # or + @timeslip.destroy == Author * Aaron Russell - (www.aaronrussell.co.uk)