Api: Invitations

List the invitations sent by your family

Route: GET /api/v1/invitations

This will return an array containing all the invitations sent to join your family. This array will also contain informations about the person who invited the member.

Example:

curl -X GET \
   -H "Accept: application/json" \
   -d 'auth_token=sYcyvuHUopjT46iMhkU5' \
    http://localhost:3000/api/v1/invitations

Will have the following output:

[
  {
    "email": "marco@paulo.fr",
    "inviter": {
      "id": 1,
      "avatar_url": "https://secure.gravatar.com/avatar/458641ed4b2725b16edbf0192ca0b2f2.png?d=mm&r=PG&s=40",
      "first_name": "Dimitri",
      "last_name": "Jorge",
      "nickname": "keny"
    },
    "status": "pending"
  },
  {
    "email": "lola@bibou.fr",
    "inviter": {
      "id": 1,
      "avatar_url": "https://secure.gravatar.com/avatar/458641ed4b2725b16edbf0192ca0b2f2.png?d=mm&r=PG&s=40",
      "first_name": "Dimitri",
      "last_name": "Jorge",
      "nickname": "keny"
    },
    "status": "pending"
  },
  {
    "email": "salut@lescopains.fr",
    "inviter": {
      "id": 1,
      "avatar_url": "https://secure.gravatar.com/avatar/458641ed4b2725b16edbf0192ca0b2f2.png?d=mm&r=PG&s=40",
      "first_name": "Dimitri",
      "last_name": "Jorge",
      "nickname": "keny"
    },
    "status": "pending"
  }
]

Create a new invitation

Route: POST /api/v1/invitation

You MUST send a email param with your query.

Example:

curl -X POST \
   -H "Accept: application/json" \
   -d 'auth_token=sYcyvuHUopjT46iMhkU5' \
   -d 'email=rodrigo@delave.ga' \
    http://localhost:3000/api/v1/posts

Will have the following output:

{
   "created_at":"2013-04-19T16:13:04Z",
   "email":"rodrigo@delave.ga",
   "family_id":1,
   "id":4,
   "status":"pending",
   "updated_at":"2013-04-19T16:13:04Z",
   "user_id":1
}

If an error occurs, it will return a 400 status code and an information about the error:

{
  "error": {
    "email": [
      "Invitation already exists"
    ]
  }
}

Important note:

• There can be only one invitation to a given email per family
• An invitations sends and email (or should, once we configure the mailer)
• When an invitation is created, the status is set to 'pending'
• When a use accepts or rejects an invitations, its status is set to 'rejected' or 'accepted'
• You can't send an invitation to someone that is already in a family

List all the invitations that have been send to you

Route: GET /api/v1/invitations/received

This call will list all the pending invitations of the current user.

Example:

curl -X GET \
   -H "Accept: application/json" \
   -d 'auth_token=Sz8kAryybkMupRsRPdFY' \
   -d 'email=rodrigo@delave.ga' \
    http://localhost:3000/api/v1/invitations/received

Will have the following output

[
  {
    "id": 4,
    "inviter": {
      "id": 1,
      "avatar_url": "https://secure.gravatar.com/avatar/458641ed4b2725b16edbf0192ca0b2f2.png?d=mm&r=PG&s=40",
      "first_name": "Dimitri",
      "last_name": "Jorge",
      "nickname": "keny"
    },
    "family": {
      "members_count": 6
    }
  },
  {
    "id": 5,
    "inviter": {
      "id": 2,
      "avatar_url": "https://secure.gravatar.com/avatar/b5c2e8036d32bbc6f20fd8b70f45373c.png?d=mm&r=PG&s=40",
      "first_name": "Jose",
      "last_name": "Rodrigues",
      "nickname": "rodrig_d"
    },
    "family": {
      "members_count": 0
    }
  }
]

Reject an invitation

Route: GET /api/v1/invitations/:id/reject

This call will reject the invitation identified by id.

Example:

curl -X GET \
   -H "Accept: application/json" \
   -d 'auth_token=Sz8kAryybkMupRsRPdFY' \
    http://localhost:3000/api/v1/invitations/5/reject

{
   "message":"Invitation successfully rejected"
}

Accept an invitation

Route: GET /api/v1/invitations/:id/accept

This call will accept the invitation identified by id and will add the current user to the family that has sent the invitation. Note: All the other pending invitations will be set to 'rejected'.

Example:

curl -X GET \
   -H "Accept: application/json" \
   -d 'auth_token=Sz8kAryybkMupRsRPdFY' \
    http://localhost:3000/api/v1/invitations/4/accept

{
  "message": "You just joined a family"
}