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.


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.


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.