Ruby wrapper for Splitwise API http://dev.splitwise.com/
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example
lib
.gitignore
Gemfile
LICENSE.txt
README.md
Rakefile
splitwise.gemspec

README.md

Splitwise Ruby Gem

A Ruby gem for the Splitwise API.

Installation

Add this line to your application's Gemfile:

gem 'splitwise'

And then execute:

$ bundle

Or install it yourself as:

$ gem install splitwise

Configuration

follow this to get required key and secret

require 'splitwise'

SPLITWISE_KEY = <YOUR_CONSUMER_KEY> 
SPLITWISE_SECRET = <YOUR_CONSUMER_SECRET>
Splitwise.access_token = access_token 

here access_token is access token obtained after authenticating app by user, more about it below.

Usage

All data returned will be in string format. Do JSON.parse(response) to convert it to json.

  • API Methods

  • Users

    • get_current_user

      Splitwise::Users.get_current_user
    • get_user

      Splitwise::Users.user_info(id) 
      # 'id' of user who shares a group or a friendship with current user
    • update_user_info

      Splitwise::Users.update_user(id, data)
      # id - current_user_id or user_id of invited user who has not logged in yet
      # data - Hash of Parameters
      • Parameters:
        • first_name, last_name, email, password, locale, date_format, default_currency, default_group_id, notification_settings

        • Eg:

          id = 123
          data = { 'first_name' => 'first', 'last_name' => 'last', ... }
          Splitwise::Users.update_user(id, data)
      • Note:
        1. A user can update anything about himself.
        2. For other users (for users who is acquainted with but haven’t logged in yet) only [first_name, last_name, email] can be updated.
  • Groups

    • list_groups : list all groups of current user

      Splitwise::Groups.list_groups
    • group_info : get group info of group_id

      Splitwise::Groups.group_info(group_id)
    • create : create group

      Splitwise::Groups.create(data)
      # data - Hash of Parameters
      • Parameters:
        • name (mandatory), group_type (optional), country_code (optional),
        • a list of group members (optional)
          1. users__ARRAYINDEX__PARAMNAME,
          2. params are either: (first_name, last_name, email) or (user_id)
    • delete: delete group

      Splitwise::Groups.delete(group_id)
      # Returns: {:success ⇒ true/false}
    • add_user_to_group: add a user to existing group

      Splitwise::Groups.add_user(data)
      # data - Hash of Parameters
      # Return: {:success ⇒ true/false, :errors ⇒ [any errors]}
      • Parameters:
        • group_id and user_id, or
        • group_id, first_name, last_name, email (should send an invite if successful and account does not already exist)
    • remove_user_from_group: remove user from an existing group

      Splitwise::Groups.remove_user(data)
      # data - Hash of Parameters (group_id, user_id)
      # Return: {:success ⇒ true/false, :errors ⇒ [any errors]}
  • Expenses

    Splitwise::Expenses.list_all_expenses
    • expense_info: get expense info of expense_id

      Splitwise::Expenses.expense_info(expense_id)
    • create_expense: create a new expense

      Splitwise::Expenses.create(data)
      # data - Hash of Parameters
      • Parameters:
        • payment, cost, description
        • refer this for more info
    • update_expense: update an expense

      Splitwise::Expenses.update_expense(expense_id, data)
      # data - Hash of Parameters
    • delete_expense: delete given expense

      Splitwise::Expenses.delete(expense_id)
  • Friends

    • list_friends: list all friends of user

      Splitwise::Friends.list_friends
    • friend_info: get friend infformation

      Splitwise::Friends.friend_info(friend_id)
    • create_friend: create a new friend

      Splitwise::Friends.create(data)
      # data - Hash of Parameters
    • delete_friend: delete a friend

      Splitwise::Friends.unfriend(friend_id)

Usage guideline to integrate with Ruby on Rails / Sinatra app

Splitwise uses OAuth 1.0 for authenticating user which means it needs one time authorization from user. Read more about it here.

I have made a sample Sinatra app as a demo of API usage. Refer example.
I am using omniauth-splitwise for authentication Splitwise API.

How to run it:

  1. cd example
  2. bundle
  3. Enter SPLITWISE_KEY and SPLITWISE_SECRET in the example_splitwise_api.rb
  4. ruby example_splitwise_api.rb
  5. Goto localhost:4567, you will be directed to authorization page.
  6. Once authorized, you can use the api.

Contributing

  1. Fork it ( https://github.com/divyum/splitwise-ruby/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

To-do's

  • detailed readme (esp expenses, groups, friends ) - [ ] examples for each type - [ ] return values for each
  • more error handling: - [ ] timeout - [ ] mandatory parameter checks
  • test cases
  • make create friends endpoint
  • make more endpoints for fetching data