Participation API

The Participation API is used to connect resources to the swarms they are a member of. Once connected, resources may produce data, consume data, or do both, depending on their level of access to the swarm. Throughout this process, the BUGswarm platform generates presence notifications and error messages when necessary in addition to passing along the messages being produced in the swarm. The Participation API makes use of HTTP streaming, meaning that once a connection has been opened, bidirectional communication between the resource and the swarm may continue until the connection is closed.

To open a connection between a resource and a swarm, send an HTTP POST request to the following URL with the following headers.

URL:

'http://api.bugswarm.net/stream?swarm_id=SWARM_ID&resource_id=RESOURCE_ID'

Replace SWARM_ID and RESOURCE_ID with the id of the swarm you would like to connect to and the resource you would like to connect with. Additionally, you may connect the resource to multiple swarms at once by appending multiple &swarm_id=SWARM_ID statements to the single swarm_id=SWARM_ID that is given above. Keep in mind that a resource must be added to the swarm using the Configuration API's Add Resource method for swarms before it may connect to the swarm and begin producing and/or consuming.

Headers:

• x-bugswarmapikey: PARTICIPATION_KEY
• transfer-encoding: chunked
• connection: keep-alive

Note that a first chunk must be sent in order for the connection to open and resource presence to be observed. This first chunk does not need to be in the 'message' format described below, or even valid JSON. However, this prevent that chunk from being viewed by the swarm. Additionally, although this use of HTTP POST allows for bidirectional communication, resources will have access to the swarm based on whether they are configured as producers, consumers, or both.

Once a connection has has been successfully opened for production, you may freely send messages from your connected resource to the swarm. However, messages must be sent with chunked encoding as JSON objects in the following formats.

• Chunked Encoding

• Chunked encoding consists of sending a hexadecimal representation of the message's size followed by the message itself, appending the characters "\r\n" to the end of each. More information about chunked encoding can be found in section 3.6.1 of this page as well as Wikipedia.

• Formats

• Public message to all swarms the resource is connected to:
  
  

  {"message": {"payload": {"x":1}}}
  

  Public message to specific swarm(s):
  
  

  {"message": {"to": ["234", "123"], "payload": {"x":1}}}
  

  Private message to specific resource in specific swarm:
  
  

  {"message": {"to": [{"swarm": "234", "resource": "222"}], "payload": {"y":2}}}
  

  Note that, within the message, the payload itself must also be a JSON object or JSON array .

  
  
  

  Receiving Messages

  Messages will be received in the following formats depending on whether they are public or private.

  
  Public message received from resource 123 as observed by all resources connected to the swarm.
  
  

  {"message": {"from": {"swarm": "234", "resource":"123"}, "public": true, "payload": {"x": 1}}}
  

  Private mesage recieved from resource 123 as observed by the receiving resource.
  
  

  {"message": {"from": {"swarm": "234", resource: "123"}, "public": false, "payload": {"y": 2}}}
  

  
  
  

  Presence and Errors

  Presence Notifications

  • Swarm Presence

  • When a resource connects to a swarm, a swarm presence notification is sent to each of the resources currently connected to that swarm. Additionally, the connecting resource receives swarm presence notifications from those resources that are currently connected. When a resource disconnects from a swarm, a swarm presence notification of type "unavailable" is sent to each of the currently connected resources.

  • Direct Presence

  • When a resource connects to its first swarm, a direct presence notification is sent to each resource under that user account that is also connected to a swarm. Additionally, the connecting resource receives direct presence notifications from all other resources under the same user account that are already connected to at least one swarm. When a resource disconnects from its last swarm, a direct presence notification of type "unavailable" is sent to each of the resources under the same user account that are connected to at leaset one swarm.

  Errors

  Errors are sent to a resource when something has gone wrong. This usually means that a resource has attempted to use the API to do something that is not permited, such as producing to a swarm when it is only connected as a consumer or attempting to connect to a swarm that it is not a member of. Errors contain a list of HTTP codes and descriptions for each error that occured during the attempted operation. Some operations my cause more than one error, so the list may have more than one element.

  Formats

  Presence Notifications

  • Sender

  • To join swarms 234 and 333:
    
    

    {"presence": {"to": ["234", "333"]}}
    

    To leave swarms 234 and 333:
    
    

    {"presence": {"to": ["234", "333"], type: "unavailable"}}
    

  • Recipient

  • When resource 222 has joined swarm 234:
    
    

    {"presence": {"from": {"swarm": "234", "resource": "222", "user": "c4milo"}}
    

    When resource 222 has left swarm 234:
    
    

    {"presence": {"from": {"swarm": "234", "resource": "222", "user": "c4milo"}, "type": "unavailable"}
    

    When a resource that is owned by the same user connects to BUGswarm:
    
    

    {"presence": {"from": {"resource": "222"}}}
    

    When a resource that is owned by the same user disconnects from BUGswarm:
    
    

    {"presence": {"from": {"resource": "222"} "type": "unavailable"}}
    

  Errors

  • Recipient

  When an error occurs:
  
  

  {"errors": [{"code": "xxx", description: "foo"}, {"code": "yyy", "description": "bar"}]}