marrily_api.md

Marrily's data can be accessed via a RESTful interface. Here are the documentation on how to access the API. Currently the data are represented via JSON format only.

1. v1 API info =============== The current API is at v1, and the all API access is over HTTP, starting with

   http://api.marrily.com/api/v1/

If the subscription is expired, you will get a 402 error for non-GET requests (except for user's authentication).

Besides the authentication-related parameters of user_id, app_token, and api_token, other required parameters are denoted with *.

2. User ========

2.1. Authentication

To access any data from Marrily, the first step is to get the api_token. To get the api_token, you have to authenticate the user by POSTing to the authenticate.

Authentication

POST /users/authenticate

with POST data of

email
password
app_token:  a SHA1 unique token for the app.

The response is

user
  - id
  - email
  - name
  - api_token
  - account: {
    - created_at
    - subscription: {
      - is_active
    }
  }
  - role

2.2. Register for a new account

POST /users

params

app_token
user[email] *
user[name] *
user[password] * 
user[password_confirmation] *
user[event_role] * = bride|groom|mother of bride|other
account[time_zone]  (optional, default to CST)

device[id] ?

response

@user.to_json (including errors)

2.3. Load application's data

Use the data from this call to populate the local database

GET /users/app_data

params

username
api_token
app_token

response

{
  @categories.to_json,
  @foods.to_json
}

3. Device ========== Register a mobile device so that it can get notified.

   TBA

4. Tasks ========= 4.1. To list all the incomplete tasks for the account:

---

GET /tasks.json

params

email
api_token
app_token

Response:

[
  task: {
    id
    account_id
    note:
    due_at
    has_reminders: 0,1
    reminder_type_ids: 1,2,3,4
  },
  task: {
    ...
  }
]

Currently the mappings from reminder_type_id to value are:

1: 15 mins
2: 30 mins
3: 1hr
4: 2hrs
5: 1 day
6: 2 days

4.2 Create a new task

POST /tasks

with POST params of

email
api_token
app_token
task[name] *
task[note]
task[due_at]
task[reminder_type_ids]= 1,2,3

Response

task: {
  id:
  name:
  due_at
  reminder_type_ids
}

4.3 To update a new task

PUT /tasks/:task_id

params:

email
api_token
app_token
task[name]
task[note]
task[:due_at]
task[reminder_type_ids]

If your HTTP client does not support PUT method, add "_method=PUT" to the params list. This is similar to how PrototypeJS simulates custom requests.

response:

task: {
  id:
  name:
  due_at:
  reminder_type_ids
}

If the account's subscription is no longer active, you will get a 402 error.

4.4. To complete a set of tasks

POST /tasks/complete

params:

email
api_token
app_token
task_ids = 1,2,3,4,5,6

Response:

{ status: success|error }

4.5. To delete a task

DELETE /tasks/:task_id

with params of

username
api_token
app_token

Response:

task : {
  id
  destroyed: true/false
}

5. Checklist =============

5.1. Load all user's checklists data

GET /checklists.json

params:

email
api_token
app_token

Response:

[
  { 
    checklist: {},
    checklist_sections: [
      checklist_section: { },
      checklist_section: { }
    ],
    checklist_items: [
      checklist_item: { },
      checklist_item: { },
    ]
  }
]

5.2. Create Checklist

POST /checklists

params:

checklist[event_id] *
checklist[name] *
checklist[description]

checklist_sections[0][name]
checklist_sections[0][position]

checklist_sections[1][name]
checklist_sections[1][position]

Include multiple checklist_sections[:index] to automatically create the sections of the checklists.

Response

5.3 Add items

POST /checklists/:checklist_id/checklist_items

params:

email
api_token
app_token
checklist_item[checklist_section_id] * need to be a valid section
checklist_item[name] * 
checklist_item[category_id]
checklist_item[description]
checklist_item[url]
checklist_item[is_completed]

response

{
  checklist: @checklist.to_json,
  checklist_item: @checklist_item.to_json
}

5.4 Update items

PUT /checklist_items/:id

params:

email
api_token
app_token
checklist_item[checklist_id] * need to be a valid checklist_id
checklist_item[checklist_section_id] * need to be a valid section
checklist_item[name] * 
checklist_item[category_id]
checklist_item[description]
checklist_item[url]
checklist_item[is_completed]

5.5. Complete Checklist Items

POST /checklists/:checklist_id/checklist_items/complete/

params

email
api_token
app_token
checklist_item_ids= comma separated list of ids, e.g. 1,2,3,4

Response

@checklist.to_json

6. Guests & Contacts =====================

6.1. Get all guests of the account

GET /guests.json

params:

email
api_token
app_token

response

{ 
  "guests": @guests.to_json,
  "contacts": @contacts.to_json
}

6.2. Create a new guest

POST /events/:event_id/guests

params:

email
api_token
app_token
contact[title]
contact[first_name]
contact[last_name]
...

contact[companions][0][first_name]
contact[companions][0][last_name]
contact[companions][0][contact_type]

response

{ 
  "guests": @guests.to_json,
  "contacts": @contacts.to_json
}

6.3. Update guest's contact info

PUT /events/:event_id/guests/:guest_id

params

email
api_token
app_token
contact[first_name]
contact[last_name]
...
contact[companions][companion_id][id]
contact[companions][companion_id][title]
contact[companions][companion_id][contact_type]
contact[companions][companion_id][first_name]
contact[companions][companion_id][last_name]
contact[companions][companion_id][_destroy] (add this to remove to the companions)

response

{ 
  "guests": @guest.to_json,
  "contacts": @contacts.to_json
}

6.4. Invite a contact to an event

POST /contacts/invite_contact_to_event

params

email
api_token
app_token

event_id
contact_id
invited=true

response:

{ 
  "guests": @guests.to_json,
}

6.5. Uninvite guest

POST /contacts/invite_contact_to_event

params

email
api_token
app_token

event_id
contact_id
invited=false

response

success|error ?

This API call will delete the contact's guest data, including companions, RSVP status, and Gift tracking, and Seating arrangement data.

6.6. Batch create new guests

Useful for import contacts from phone.

POST /events/:event_id/guests/batch_create

params

email
api_token
app_token
contact[0][title]
contact[0][first_name]
contact[0][last_name]
...

contact[1][title]
contact[1][first_name]
contact[1][last_name]    

response

@guests.to_js 

6.7. Update Guest's RSVP status and food option

PUT /guests/:guest_id/rsvp

params

email
api_token
app_token
guest[rsvp_status] = ''|'accepted'|'declined'
guest[food_id]
guest[guests][:guest_id][rsvp_status]
guest[guests][:guest_id][food_id]

response

@guest.to_json

6.8. Update Guest' Gift

POST /guests/:guest_id/gifts

params

email
api_token
app_token
guest[gift_received] = true|false
gift[amount] = float
gift[description]

response

{
  @guest.to_json,
  @gift.to_json
}

6.9. Toggle Thankyou Sent

POST /guests/:guest_id/toggle_thank_you_sent

params

email
api_token
app_token
guest[thank_you_sent] = true|false

response

{ "status": success }

7. Events ==========

7.1. List all events

GET /events.json

Response

[
  @event[0].to_json,
  @event[1].to_json,
]

7.2. Create New Event

POST /events/

params

email
api_token
app_token
event[name] 
event[when]
event[enable_food_selection]
event[budget_amount]
event[estimated_guests_count]

response

@event.to_json (including any available food-options)

7.3. Update Event

PUT /events/:event_id

params

email
api_token
app_token
event[name] 
event[when]
event[enable_food_selection]
event[budget_amount]
event[estimated_guests_count]

response

@event.to_json (including any available food-options)

8. Expenses ============

8.1. List all events

GET /expenses.json

Response

@expenses.to_json

8.2. Create New Event

POST /expenses.json

params

email
api_token
app_token
expense[event_id] *
expense[category_id]
expense[amount] *
expense[paid_on] *
expense[note]        

response

@expense.to_json (with errors hash as well)

8.3. Update Event

PUT /expenses/:expense_id.json

params

email
api_token
app_token
expense[event_id] *
expense[category_id]
expense[amount] *
expense[paid_on] *
expense[note]        

response

@expense.to_json (with errors hash as well)