Class: ApiController

Inherits:

ApplicationController

Object
ApplicationController
ApiController

show all

Includes:

ApiDeprecatedModule, ApiExperimentalModule, ApiSyncModule

Defined in:

app/controllers/api_controller.rb

Overview

Astrid JSON API controller

Constant Summary

CURRENT_API_VERSION =

Instance Method Summary (collapse)

- (Hash) user_signin

Creates or signs in a user.
- (Hash) user_save

Saves changes to user profile.
- (Hash) user_add_auth

Adds an authentication token for a supported OAUTH service.
- (Hash) user_invite

Send email invite to someone.
- (Hash) user_set_status

Sets user friendship status.
- (Hash) user_reset_password

Send user forgotten password link.
- (Hash) user_status

Get user status.
- (Hash) users_exist

Checks if each user in the specified email list exists, returning a list of only those that do.
- (Hash) task_save

Saves a new or existing task.
- (Hash) task_show

Get information about a task.
- (Hash) task_set_following

Follow or unfollow task notifications.
- (Hash) task_update_people

Adds or removes people task is shared with.
- (Hash) task_share_social

Share this task on a social network.
- (Hash) task_list

Gets a list of all of this user's tasks.
- (Hash) list_order

Read or update list manual ordering.
- (Hash) task_attachment_create

Adds attachment to task.
- (Hash) task_attachment_remove

Removes attachment from task.
- (Hash) task_attachment_list

Lists task attachments.
- (Hash) list_save

Saves a new or existing list.
- (Hash) list_show

Get information about a list.
- (Hash) list_list

Gets a list of all of this user's lists.
- (Hash) tag_save
- (Hash) tag_show
- (Hash) tag_list
- (Hash) activity_list

Gets a list of all of recent site activity.
- (Hash) model_history_list

Gets a list of all of changes to the given object.
- (Hash) comment_add

Add a comment to a task or list.
- (Hash) user_show

Gets information and tasks for this user.
- (Hash) user_list

Gets a list of users and their recent activity.
- (Hash) featured_lists

Gets a list of all featured lists.
- (Hash) featured_list_subscribe

Subscribe to a featured list.
- (Hash) time

Test API to get server time.

Instance Method Details

- (`Hash`) user_signin

Creates or signs in a user

Examples:

Example Request

/user_signin?email=test@user.com&provider=password&secret=password

Example Response

{
  "token": "thcglhsoi6h4jolv",
  "new": false,
  "id": 1,
  "name": "Test User",
  "first_name": "Test",
  "last_name": "User",
  "email": "test@user.com",
  "picture": "http://url.to/photo",
  "quiet_start": 22,
  "quiet_end": 8,
  "premium": false,
  "status": "success"
}

Parameters:

email (String) —

user email address
first_name (String) —

user first name (required for new users)
last_name (String) —

user last name (required for new users)
provider (String) —
one of the following:
- "facebook": facebook oauth
- "twitter": twitter oauth
- "password": non-oauth password
secret (String) —

oauth token (or password if password provider)
oauth_secret (String) —

oauth secret (for twitter)
timezone (String) —

tz name, i.e. 'America/Los_Angeles' (required for new users)

JSON Response:

{
   'id': user id
   'name': user full name
   'first_name': user first name
   'last_name': user last name
   'picture': user photo
   'token': use this to authenticate requests
   'new': true if user is new to Astrid. You should welcome them!
   'quiet_start': hours quiet hours start (0..24)
   'quiet_end': hours quiet hours end (0..24)
   'premium': true if user is premium
}

- (`Hash`) user_save

Saves changes to user profile

Parameters:

first_name (String) —

user first name (optional)
last_name (String) —

user last name (optional)
description (String) —

brief user bio (optional)
picture (File) —

multi-part MIME picture (optional)

JSON Response:

{
   'id': user id
   'first_name': user first name
   'last_name': user last name
   'description': user description
   'picture': user photo url
}

- (`Hash`) user_add_auth

Adds an authentication token for a supported OAUTH service

Parameters:

provider (String) —

one of "facebook" or "twitter"
oauth_token (String) —

oauth token
oauth_secret (String) —

oauth secret (required for twitter)

- (`Hash`) user_invite

Send email invite to someone

Parameters:

email (String) —

invitee email address
name (String) —

invitee name (optional)
message (String) —

invitation message (optional)

- (`Hash`) user_set_status

Sets user friendship status

Parameters:

id (Integer) —

other user id
status (String) —
one of:
- request - request friendship
- approve - approve friendship request
- ignore - ignore friendship request
- unfriend - remove friendship

JSON Response:

{
   'status': new status
}

- (`Hash`) user_reset_password

Send user forgotten password link

Parameters:

email (String) —

user's email

JSON Response:

{
   'email': email where instructions were sent (may be different from param)
}

- (`Hash`) user_status

Get user status

{
   'id': user's id (note, user ids can change when two users are merged into one)
   'first_name': user's first name
   'last_name': user's last name
   'name': user's name
   'picture': user's picture
   'quiet_start': hours quiet hours start
   'quiet_end': hours quiet hours end
   'premium': true if user is premium
}

- (`Hash`) users_exist

Checks if each user in the specified email list exists, returning a list of only those that do

Parameters:

email_list (Array) —

(required)

- (`Hash`) task_save

Saves a new or existing task

Examples:

Example Request

/task_save?title=Eat+snacks&token=thcglhsoi6h4jolv

Example Response

{
  "user": {
      "id": 1,
      "first_name": "Test",
      "last_name": "User",
      "name": "Test User",
      "picture": "http://url.to/photo"
  },
  "user_id": 1,
  "id": 545,
  "title": "Eat snacks",
  "importance": 2,
  "due": 0,
  "has_due_time": false,
  "completed_at": 0,
  "created_at": 1340445273,
  "updated_at": 1340445274,
  "deleted_at": 0,
  "repeat": "",
  "privacy": "private",
  "notes": "",
  "tags": [],
  "comment_count": 0,
  "creator": {
      "id": 1,
      "first_name": "Test",
      "last_name": "User",
      "name": "Test User",
      "picture": "http://localhost:3000/system/pictures/27/medium/Howard Dean.jpg?1332989952"
  },
  "attachments": [],
  "status": "success"
}

Parameters:

id (Integer) —

if set, will update an existing task (optional)
title (String) —

task title (required for new tasks)
importance, (Integer) —

0..3 (optional)
due (Time) —

due date (optional)
has_due_time (Boolean) —

whether to read time component of due date (optional)
created_at (Time) —

time this task was created (for duplicate detection) (optional)
has_due_time (Boolean) —

whether task due at specific time, 0 or 1 (optional)
completed_at (Time) —

time task was completed, or 0 (optional)
deleted_at (Time) —

time task was deleted, or 0 (optional)
repeat (String) —

RRULE recurrence token (see RFC 2445) (optional)
notes (String) —

text notes (optional)
public (Boolean) —
one of the following (optional)
- 0: task is not visible to everyone on Astrid
- 1: task is visible to everyone on Astrid
tags (Array<String>) —

array of lists (i.e. tags[]=first&tags=second) (optional)
tag_ids (Array<Integer>) —

array of list ids. can be mixed with tags parameter (optional)
user_email (String) —

user email to assign task to (optional)
user_id (Integer) —

user id to assign task to, or -1 for unassigned (optional)
send_url (Boolean) —

whether return hash should include a url to this task (optional)
share_with (Array<String>) —

list of emails to share task with (optional)
message (String) —

email message to send to shared users (if using share_with) (optional)
share_subject (String) —

email message to send to shared users (if using share_with) (optional)
send_link (Boolean) —

whether to send a link parameter with a link to the task (optional)

JSON Response:

task hash (see #task_show)

- (`Hash`) task_show

Get information about a task

Parameters:

id (Integer) —

item id

JSON Response:

{
   'id': task id
   'user_id': user id
   'user': { 'id': id, 'name': name; 'picture': avatar url }
   'creator': { 'id': id, 'name': name; 'picture': avatar url }
   'title': task title
   'due': due date, SSEUTC. 0 if unset
   'has_due_time': whether task has due time, boolean
   'repeat': repeat RRULE (see RFC 2445)
   'privacy': one of 'public', or 'private'
   'created_at': creation date, SSEUTC
   'completed_at': completion date, SSEUTC. 0 if uncomplete
   'deleted_at': deletion date, SSEUTC. 0 if not deleted
   'notes': task notes
   'comment_count': # comments
   'tags': [ { 'id': id, 'name': list name } ]
   'attachments': [ see {#task_attachment_create} ]
}

- (`Hash`) task_set_following

Follow or unfollow task notifications

Parameters:

id (Integer) —

task id to follow
following (Boolean) —

1 if following, 0 otherwise

- (`Hash`) task_update_people

Adds or removes people task is shared with

Parameters:

id (Integer) —

task id
add (Array<String or Integer>) —

array of emails or user ids to add
remove (Array<String or Integer>) —

array of emails or user ids to remove
send_email (Boolean) —

if 1, sends email to new people
subject (String) —

email subject
message (String) —

email message

JSON Response:

task hash (see #task_show)

- (`Hash`) task_share_social

Share this task on a social network

Parameters:

id (Integer) —

task id
network (String) —

one of "facebook" or "twitter"
message (String) —

message to post with task (optional)
provider (String) —

one of "facebook" or "twitter" (optional, used if not logged in already)
oauth_token (String) —

oauth token (see provider)
oauth_secret (String) —

oauth secret (see provider, required for twitter)

- (`Hash`) task_list

Gets a list of all of this user's tasks

Parameters:

modified_after (Integer) —

only modified after this time (SSEUTC) (optional)
user_id (Integer) —

if set, show tasks shared with this user (optional)
tag_id (Integer) —

if set, show tasks for given list (optional)
active (Boolean) —

if set, only show active tasks (optional)
completed (Boolean) —

if set, only show completed tasks (optional)
send_links (Boolean) —

if set, include a link parameter with each task (optional)

JSON Response:

{
   'list': [ task hashes (see {#task_show} ],
   'time': current server time SSEUTC
}

- (`Hash`) list_order

Read or update list manual ordering. One of tag_id or filter must be specified

Parameters:

tag_id (Integer) —

tag id
filter (String) —

name of filter (e.g. 'all', 'today', 'nolist')
order (String) —

new list ordering (optional)
sort (String) —

new list sort method (optional, one of 'auto', 'manual', 'importance', 'due', 'created', or 'modified')

JSON Response:

{
   'order': array of (nested) task ids, or null
   'sort': sorting preference, or null for default
}

- (`Hash`) task_attachment_create

Adds attachment to task

Parameters:

task_id (Integer) —

task id
file (File) —

multipart file attachment

JSON Response:

{
   'id': attachment id
   'name': file name
   'url': url to file
   'content_type': file mimetype
   'size': file size (in bytes)
}

- (`Hash`) task_attachment_remove

Removes attachment from task

Parameters:

id (Integer) —

attachment id

- (`Hash`) task_attachment_list

Lists task attachments

Parameters:

task_id (Integer) —

task id

JSON Response:

{
  'list': [ task attachment hash (see {#task_attachment_create} ]
}

- (`Hash`) list_save

Saves a new or existing list

Examples:

Example Request

/list_save?name=My+Favorite+Things&token=thcglhsoi6h4jolv

Example Response

{
  "user": {
      "id": 1,
      "first_name": "Test",
      "last_name": "User",
      "name": "Test User",
      "picture": "http://url.to/photo"
  },
  "id": 295,
  "name": "My Favorite Things",
  "description": null,
  "picture": "http://astrid.com/assets/default/icn_dfi3_130.png",
  "is_silent": false,
  "is_public": false,
  "is_favorite": 0,
  "emergent": false,
  "created_at": 1340447987,
  "updated_at": 1340447987,
  "deleted_at": 0,
  "members": [],
  "status": "success"
}

Parameters:

id (Integer) —

if set, will update an existing list (optional)
name (String) —

list name (optional)
description (String) —

list description (optional)
members (Array<Integer or String>) —

mixed array of user ids or e-mails (optional)
is_silent (Boolean) —

whether user wants to silence alerts (0 or 1) (optional)
reusable (Boolean) —

if set, markes this new list as reusable (experimental) (optional)
from_tag_id (Integer) —

if making reusable, read values from this list (experimental) (optional)

JSON Response:

list hash (see #list_show)

- (`Hash`) list_show

Get information about a list

Parameters:

id (Integer) —

item id
name (String) —

item name (one of id or name is required)

JSON Response:

{
   'id': list id
   'user': { 'id': id, 'name': name, 'picture': avatar url }
   'name': list name
   'description': list description
   'picture': picture url,
   'is_silent': whether user has silenced notifications,
   'is_favorite': is this a 'favorited' list,
   'emergent': whether this was an auto-generated 'emergent' list,
   'created_at': SSEUTC list was created,
   'updated_at': SSEUTC list was last modified,
   'deleted_at': SSEUTC list was deleted, or 0 if not deleted,
   'tasks': # of active tasks in this list (only with /list_list method)
   'members': [ { user hashes } ]
}

- (`Hash`) list_list

Gets a list of all of this user's lists

Parameters:

user_id (Integer) —

show lists involving this user (optional)

JSON Response:

{
   'list': [ (see {#list_show} for individual list hash) ],
   'time': current server time SSEUTC
}

- (`Hash`) tag_save

- (`Hash`) tag_show

- (`Hash`) activity_list

Gets a list of all of recent site activity. If no parameters are passed, a list of other people's activity that the current user has visibility into will be returned.

Note: parameters are mutually exclusive

Parameters:

user_id (Integer) —

get latest by this user (optional)
task_id (Integer) —

get latest about this task (optional)
tag_id (Integer) —

get latest about this list (optional)
include_me (Boolean) —

get all activity visible to logged in user (optional)

JSON Response:

{
  'list': [
    {
      'id': activity id,
      'user': user hash,
      'action': what the user did, i.e. "created Eat my lunch",
      'created_at': activity creation SSEUTC

      // --- these are not present in every activity ---
      'other_user_id': user id,
      'task_id': task id,
      'tag_ids': comma separating list of tag ids with trailing comma,
      'message': the comment, suggestion, etc,
    }
  ]
}

- (`Hash`) model_history_list

Gets a list of all of changes to the given object. Sends entries 10 at a time. For a reference implementation on displaying history, see this gist: gist.github.com/timsu/4726684

These parameters apply to all requests:

Parameters:

task_id (Integer) —

get history for task by id
tag_id (Integer) —

get history for list by id
modified_after (Integer) —

only send history after this time (SSEUTC) (optional)
offset (Integer) —

offset history by the given # (optional, for paging)

JSON Response:

{
  'list': [
    {
      'id': history id,
      'user_id': user id (will be sent in users hash),
      'column': column that was affected,
      'created_at': activity creation SSEUTC
      'prev': previous value
      'value': new value
      'flags': hash of flags:
         'offline' - this edit was recorded while device was offline
         'truncated' - the value contained for this edit was truncated
         'everyone' - this edit applies to everyone (when renaming list name)

      // --- if this history pertains to a task within the list ---
      'task': [ task id, task title ],
    }
  ],
  'users': {
     1: { name: "Bob Jones", picture: "http://..." }
  }
  'has_more': next offset number (e.g. 10 if you pass offset = 0) if there are more results, or false
}

- (`Hash`) comment_add

Add a comment to a task or list

Note: parameters are mutually exclusive

Parameters:

task_id (Integer) —

task id (optional)
tag_id (Integer) —

list id (optional)
message (String) —

comment body (one of message or picture required)
picture (File) —

picture to attach (one of message or picture required)

JSON Response:

{
   'id': comment id
   'picture': picture url (if picture was transmitted)
}

- (`Hash`) user_show

Gets information and tasks for this user

Examples:

Example Request

/user_show?id=1

Example Response

{
  "id": 1,
  "name": "Test User",
  "username": "testuser",
  "connection": "success",
  "picture": "http://url.to/avatar",
  "is_following": 0,
  "stats": {
      "active": 38,
      "completed": 2,
      "inspired": 0,
      "supported": 4
  }
}

Parameters:

id (Integer) —

user id

JSON Response:

{
  id: user id
  name: name
  username: username
  picture: user picture url
  connection: one of <null>, friends, pending, or other_pending
  description: user description
  stats: { active:#, completed:#, inspired:#, supported:# }
}

- (`Hash`) user_list

Gets a list of users and their recent activity

Unless query parameter is passed, will get list of user's 'people', who are defined in Astrid as users the user has explicitly requested to be friends with and users the user has shared tasks with.

Examples:

Example Request

/user_list

Example Response

{
  "list": [
    {
      "id": 1,
      "thumb": "http://url.to/thumbnail",
      "picture": "http://url.to/avatar",
      "name": "Test User",
      "status": "friends",
      "stats": [ 38, 2, 0, 4 ]
  },
  {
      "id": 15,
      "thumb": "http://url.to/thumbnail",
      "picture": "http://url.to/avatar",
      "name": "Another Friend",
      "status": "friends",
      "stats": [ 3, 0, 0, 0 ]
  }
  "time": 1340612382,
  "status": "success"
}

Parameters:

modified_after (Time) —

only get users modified after certain time (optional)
query (String) —
- search query (optional)

JSON Response:

{
  'list' [
    { id: item id,
      name: user name,
      picture: picture url,
      thumb: picture thumbnail url,
      status: one of <null>, friends, pending, or other_pending
      stats: array of [active, completed, inspired, supported]
      activity: user's public activity (see {#activity_list} for format)
    }
  ],
}

- (`Hash`) featured_lists

Gets a list of all featured lists

Examples:

Example Request

/featured_lists

Example Response

{
  "list": [
    {
      "id": 11,
      "name": "How to cook delicious food",
      "description": "I teach you all the secrets",
      "picture": "http://url.to/list_image",
      "created_at": 1323214409,
      "updated_at": 1326511517,
      "deleted_at": 0,
      "author": "Top Chef",
      "author_url": "http://topchef.com",
      "link": "",
      "link_url": ""
    },
  ],
 "time": 1340612968,
 "status": "success"
}

Parameters:

modified_after (Integer) —

show only featured lists modified after a certain time

JSON Response:

{
   'list': [
      {
         'id': featured list id,
         'name': list name,
         'description': text description,
         'picture': list picture,
         'author': author of this list,
         'author_url': url for author (optional),
         'link': title of article related to this list (optional),
         'link_url': url of article related to this list (optional),
      }
   ]
}

- (`Hash`) featured_list_subscribe

Subscribe to a featured list

Parameters:

id (Integer) —

featured list id

JSON Response:

tag hash of your new tag based on the featured one (see #list_show)

- (`Hash`) time

Test API to get server time

JSON Response:

{
   'time': server time in seconds since epoch
}

Class: ApiController

Overview

Constant Summary

Instance Method Summary (collapse)

Instance Method Details

- (Hash) user_signin

- (Hash) user_save

- (Hash) user_add_auth

- (Hash) user_invite

- (Hash) user_set_status

- (Hash) user_reset_password

- (Hash) user_status

- (Hash) users_exist

- (Hash) task_save

- (Hash) task_show

- (Hash) task_set_following

- (Hash) task_update_people

- (Hash) task_share_social

- (Hash) task_list

- (Hash) list_order

- (Hash) task_attachment_create

- (Hash) task_attachment_remove

- (Hash) task_attachment_list

- (Hash) list_save

- (Hash) list_show

- (Hash) list_list

- (Hash) tag_save

- (Hash) tag_show

- (Hash) tag_list

- (Hash) activity_list

- (Hash) model_history_list

- (Hash) comment_add

- (Hash) user_show

- (Hash) user_list

- (Hash) featured_lists

- (Hash) featured_list_subscribe

- (Hash) time

- (`Hash`) user_signin

- (`Hash`) user_save

- (`Hash`) user_add_auth

- (`Hash`) user_invite

- (`Hash`) user_set_status

- (`Hash`) user_reset_password

- (`Hash`) user_status

- (`Hash`) users_exist

- (`Hash`) task_save

- (`Hash`) task_show

- (`Hash`) task_set_following

- (`Hash`) task_update_people

- (`Hash`) task_share_social

- (`Hash`) task_list

- (`Hash`) list_order

- (`Hash`) task_attachment_create

- (`Hash`) task_attachment_remove

- (`Hash`) task_attachment_list

- (`Hash`) list_save

- (`Hash`) list_show

- (`Hash`) list_list

- (`Hash`) tag_save

- (`Hash`) tag_show

- (`Hash`) tag_list

- (`Hash`) activity_list

- (`Hash`) model_history_list

- (`Hash`) comment_add

- (`Hash`) user_show

- (`Hash`) user_list

- (`Hash`) featured_lists

- (`Hash`) featured_list_subscribe

- (`Hash`) time