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:
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:
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:
Fails if:
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:
Optional:
- color [string]
- hover_color [string]
- sort_order [int]
Returns:
Fails if:
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:
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:
Parameters:
Notes:
- Returns the total of all entries by the logged in user, within the given period, and optionally scoped by a given category.
Sorry, comments are closed for this article.