Invitations

Send, list, and respond to invitations using the RESTful API.

Send

URL: http://api.bugswarm.net/swarms/SWARM_ID/invitations
Method: POST
Headers:
"x-bugswarmapikey: ${API_KEY}",
"content-type: application/json"
Parameters (Required): None
Parameters (Optional): None

BUGswarm provides a unique social aspect to cloud messaging between embedded devices. Invitations allow the owners of swarms to let other users' resources join their swarms as producers or consumers. This method sends an invitation to a specific resource for a given user to join the specified swarm.

Body: A JSON file containing the information of the invitation to be sent. The "description" field is optional.

{
    "to": "other username",
    "resource_id": "16f101010e80dd123b87363af759cc22cf49ff5f",
    "resource_type": "consumer",
    "description": "Hey. Come join my awesome swarm!"
}

Usage: Create a JSON file with the name invitation.json and matching the above format. Then execute:

curl -X POST -d@invitation.json --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" --header "content-type: application/json" http://api.bugswarm.net/swarms/SWARM_ID/invitations

Returns: The sent invitation in JSON format.

{
    "id": "fba0ca4bc9c63a964d9781c5487617e5f17dffd9",
    "from": "username",
    "swarm_id": "3a147bd1a79a7d075b8cd2f1d48db9719c1f6739",
    "description": "Hey. Come join my awesome swarm!",
    "resource_type": "consumer",
    "resource_id": "16f101010e80dd123b87363af759cc22cf49ff5f",
    "to": "other username",
    "sent_at": "2011-10-10T03:12:11.773Z",
    "status": "new"
}

Respond

URL: http://api.bugswarm.net/resources/RESOURCE_ID
> /invitations/INVITATION_ID
Method: PUT
Headers:
"x-bugswarmapikey: ${API_KEY}",
"content-type: application/json"
Parameters (Required): None
Parameters (Optional): None

At any point in time, users may choose to respond to pending invitations for a given resource. Use this method to either accept or reject these invitations.

Body: A JSON file containing the status of the response, either accepting ("accept") or rejecting ("reject") the invitation.

{
    "status": "accept"
}

Usage: Create a JSON file with the name response.json and matching the above format. Then execute:

curl -X PUT -d@invitation.json --header "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" --header "content-type: application/json" http://api.bugswarm.net/resources/RESOURCE_ID/invitations/INVITATION_ID

Returns: The invitation with an updated "status" field and either an "accepted_at" or "rejected_at" field.

{
    "accepted_at": "2011-10-10T03:28:56.083Z",
    "description": "Hey. Come join my awesome swarm!",
    "from": "other username",
    "id": "fba0ca4bc9c63a964d9781c5487617e5f17dffd9",
    "resource_id": "16f101010e80dd123b87363af759cc22cf49ff5f",
    "resource_type": "consumer",
    "sent_at": "2011-10-10T03:12:11.773Z",
    "status": "accepted",
    "swarm_id": "3a147bd1a79a7d075b8cd2f1d48db9719c1f6739",
    "to": "username"
}

List Sent

URL: http://api.bugswarm.net/swarms/SWARM_ID/invitations
Method: GET
Headers:
"x-bugswarmapikey: ${API_KEY}"
Parameters (Required): None
Parameters (Optional): None

Use this method to monitor the status of invitations sent to resources to join a given swarm.

Usage:

curl -X GET "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/swarms/SWARM_ID/invitations

Returns: A list of invitations sent for the given swarm.

[
    {
        "id": "fba0ca4bc9c63a964d9781c5487617e5f17dffd9",
        "from": "username",
        "swarm_id": "3a147bd1a79a7d075b8cd2f1d48db9719c1f6739",
        "description": "Hey. Come join my awesome swarm!",
        "resource_type": "consumer",
        "resource_id": "16f101010e80dd123b87363af759cc22cf49ff5f",
        "to": "other username",
        "sent_at": "2011-10-10T03:12:11.773Z",
        "status": "new"
    },
    {
        "accepted_at": "2011-10-10T03:28:56.083Z",
        "id": "b773a3c03b413d0f8398913aff719a00b7ef2d5"
        "from": "username",
        "swarm_id": "3a147bd1a79a7d075b8cd2f1d48db9719c1f6739",
        "description": "Hey. Come join my awesome swarm!",
        "resource_type": "producer",
        "resource_id": "052be4babe6efa128fa9a09997d4562250156aae"
        "to": "other username",
        "sent_at": "2011-10-10T03:12:11.773Z",
        "status": "accepted"
    }
]

List Received

URL:
http://api.bugswarm.net/invitations
http://api.bugswarm.net/resources/RESOURCE_ID/invitations
Method: GET
Headers:
"x-bugswarmapikey: ${API_KEY}"
Parameters (Required): None
Parameters (Optional): None

Use this method to keep track of what invitations you have received. You may either list all invitations received by your user account by using the http://api.bugswarm.net/invitations URL, or list invitations received by a specific resource by using the http://api.bugswarm.net/resources/RESOURCE_ID/invitations URL.

Usage:

curl -X GET "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/invitations
curl -X GET "x-bugswarmapikey: 911cbc244827dba9c6dbdd09aff3e5e8fe5eee02" http://api.bugswarm.net/resources/RESOURCE_ID/invitations

Returns: A list of invitations sent to the user or a specific resource.

[
    {
        "id": "fba0ca4bc9c63a964d9781c5487617e5f17dffd9",
        "from": "other username",
        "swarm_id": "3a147bd1a79a7d075b8cd2f1d48db9719c1f6739",
        "description": "Hey. Come join my awesome swarm!",
        "resource_type": "consumer",
        "resource_id": "16f101010e80dd123b87363af759cc22cf49ff5f",
        "to": "username",
        "sent_at": "2011-10-10T03:12:11.773Z",
        "status": "new"
    },
    {
        "accepted_at": "2011-10-10T03:28:56.083Z",
        "id": "b773a3c03b413d0f8398913aff719a00b7ef2d5"
        "from": "other username",
        "swarm_id": "3a147bd1a79a7d075b8cd2f1d48db9719c1f6739",
        "description": "Hey. Come join my awesome swarm!",
        "resource_type": "producer",
        "resource_id": "052be4babe6efa128fa9a09997d4562250156aae"
        "to": "username",
        "sent_at": "2011-10-10T03:12:11.773Z",
        "status": "accepted"
    }
]