Tweetwhatyouspend has just launched a RESTful API that will allow developers like you to create a wide assortment of applications and widgets to connect with the Tweetwhatyouspend back-end. The API was initially developed to support the creation of a Tweetwhatyouspend mobile phone app (which is underway for the iPhone) and has been since opened up to you!

The API allows developers to create cash tracking applications using Tweetwhatyouspend’s back-end. It allows you to create and manage user information, post and retrieve Cash Journal entries, create new categories and access data trends. Below are the top-level API end-points which are detailed in the following article:

• Users
• Journal Entries
• Categories
• Trend

If you have questions, or ideas for improvements, please contact info (@) tweetwhatyouspend (dot) com for more information.

Users

Update user - PUT to /users/:login.xml - private

Optional:

• currency_id [int]
• location [string]
• time_zone [string]
• twitter_pic [string]
• privacy_setting [boolean]

Fails if:

• “login” is not the logged-in user’s login
• Invalid data
• User tries to update any of: email, password, login, twitter_name

Notes:

• Assuming login, email, password are not updatable through the API.

Create a user - POST to /users.xml - public

Requires:

• twitter_name [string] - login is assumed
• email [string]
• password [string]

Optional:

• currency_id [int]
• location [string]
• time_zone [string]
• twitter_pic [string]
• privacy_setting [boolean]

Returns:

• The new user in XML form

Fails if:

• twitter_name/password are invalid Twitter credentials
• Fails established user model validations (login unique, password length, etc.)
• Invalid data

Notes:

• Bypasses any password/email confirmation process, creates user immediately.
• “login” and “password” must be valid Twitter credentials, which will be duped as the local user account’s credentials.
• Twitter fields (location, pic) will be filled in when user is created
• Updating non-essential fields requires a separate update call

Fetch user - GET to /users/:login.xml - public

Returns:

• login [string]
• email [string]
• twitter_name [string]
• twitter_pic [string]
• location [string]
• time_zone [string]
• created_at [datetime]
• updated_at [datetime]
• currency [object]
  • name [string]
  • abbreviation [string]
  • symbol [string]
  • delimitor [string]
  • created_at [datetime]
  • updated_at [datetime]

Fails if:

• “login” is not a valid user

Fetch most recent users - GET to /users.xml - public

Returns:

• A list of users, each having the same data as when fetched individually.

Parameters:

• number [int] (optional)

Notes:

• The number parameter is the number of users to return, defaults to 10

Journal Entries

Create journal entry - POST to /entries.xml - private

Required:

• item_name [string]
• price [int]

Returns:

• The new entry in XML form

Optional:

• category_id [int]

Fails if:

• Model validations fail

Notes:

• user_id will be assumed from the logged in user
• category_id, if given, will be used to create a new entry in the join table if an existing association doesn’t already exist, otherwise it will update any pre-existing association.

Update journal entry - PUT to /entries/:id.xml - private

Optional:

• item_name [string]
• price [int]
• category_id [int]

Fails if:

• Model validations fail
• Entry does not belong to the logged-in user

Notes:

• category_id, if given, will be used to create a new entry in the join table if an existing association doesn’t already exist, otherwise it will update any pre-existing association.

Delete journal entry - DELETE to /entries/:id.xml - private

Fails if:

• Entry does not belong to the logged-in user
• Entry doesn’t exist

Fetch list of one’s own journal entries - GET to /entries.xml - private

Returns (for each entry):

• item_name [string]
• price [int]
• created_at [datetime]
• updated_at [datetime]
• category object:
  • Same fields as when fetching categories at /categories.xml

Parameters (optional):

• keyword [string]
• category_id [id or string]
• per_page [int]
• page [int]

Notes:

• keyword will be used to do a basic search and filter results
• If category_id is “uncategorized”, will return uncategorized entries
• per_page, page are basic pagination parameters
• For display purposes, wouldn’t it make sense to return category name versus ID or both? What makes sense from your POV? How otherwise would you get the category name for an entry? With a separate API call for each entry?

Fetch list of all public journal entries - GET to /entries/public.xml - public

Returns:

• Same as private entries list
  • It should also return the associated user login and/or user_id as well.

Parameters:

• Same as private entries list

Categories

Fetch list of one’s own categories - GET to /categories.xml - private

Returns (for each category):

• name [string]
• color [string]
• hover_color [string]
• created_at [datetime]
• updated_at [datetime]
• default [boolean]

Notes:

• If the user has no user-made categories, the default categories will get returned

Create category - POST to /categories.xml - private

Required:

• name [string]

Optional:

• color [string]
• hover_color [string]
• sort_order [int]

Returns:

• XML of the new category

Fails if:

• No name is given

Update category - PUT to /categories/:id.xml - private

Optional:

• name [string]
• color [string]
• hover_color [string]
• sort_order [int]

Fails if:

• Category doesn’t belong to the logged-in user
• Invalid data is given

Delete category - DELETE to /categories/:id.xml - private

Fails if:

• Category doesn’t belong to the logged-in user

Fetch list of default categories - GET to /categories/default.xml - public

Returns:

• Same fields as list of private categories

Trend

Public Trend - GET to /trend/public.xml - public

Returns:

• total_spent [int]

Parameters:

• period - [day, week, month] - defaults to ‘day’
• category_id [ID, ‘uncategorized’] - defaults to null (all entries)

Notes:

• Returns the total of all entries by users whose privacy_setting is set to false, within the given period, and optionally scoped by a given category.

Private Trend - GET to /trend/private.xml - private

Returns:

• Same as the public trend

Parameters:

• Same as the public trend

Notes:

• Returns the total of all entries by the logged in user, within the given period, and optionally scoped by a given category.