-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathparticipation_api.html
More file actions
373 lines (311 loc) · 12.9 KB
/
participation_api.html
File metadata and controls
373 lines (311 loc) · 12.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for Linux (vers 25 March 2009), see www.w3.org">
<title>BUGswarm Developers</title>
<link rel="stylesheet" href="bootstrap/bootstrap.css" type=
"text/css">
<link rel="stylesheet" href="css/this.css" type="text/css">
<link rel="stylesheet" href=
"js/google-code-prettify/prettify.css" type="text/css">
<script src="http://code.jquery.com/jquery-1.5.2.js" type=
"text/javascript">
</script>
<script src="js/google-code-prettify/prettify.js" type=
"text/javascript">
</script>
<script src="js/application.js" type="text/javascript">
</script>
<script src="js/google-analytics.js" type="text/javascript">
</script>
</head>
<body>
<!-- NAVIGATION-->
<div class="topbar">
<div class="topbar-inner">
<div class="container">
<h3><a id="banner" href="index.html" name=
"banner"><img src="images/bs_logo.png"></a></h3>
<ul class="nav">
<li class="dropdown nav-dropdown">
<a href="documentation.html" class=
"dropdown-toggle">Documentation</a>
<ul class="dropdown-menu">
<li><a href=
"configuration_api.html">Configuration</a></li>
<li><a href=
"participation_api.html">Participation</a></li>
</ul>
</li>
<li><a href="tools.html">Tools</a></li>
<li><a href="libraries.html">Libraries</a></li>
<li><a href="tutorial.html">Tutorial</a></li>
<li><a href="applications.html">Applications</a></li>
<li><a href="hardware.html">Hardware</a></li>
<li><a href="contact.html">Contact</a></li>
</ul>
</div>
</div>
</div><!-- CONTAINER-->
<div class="container">
<!-- Path-->
<div class="page-header">
<a href="index.html">Home</a> → <a href=
"documentation.html">Documentation</a> → Participation
API
</div><!-- Jump to dropdown-->
<div class="topbar-inner jump-bar">
<div class="nav jump-nav">
<div class="dropdown jump-dropdown">
<a href="documentation.html" class=
"jump-header dropdown-toggle">Jump to</a>
<ul class="dropdown-menu jump-menu">
<li><a href="#opening-a-connection">Opening a
Connection</a></li>
<li><a href="#sending-messages">Sending
Messages</a></li>
<li><a href="#receiving-messages">Receiving
Messages</a></li>
<li><a href="#presence-and-errors">Presence and
Errors</a></li>
</ul>
</div>
</div>
</div><!-- Header-->
<h1>Participation API</h1>
<p>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.</p><br>
<div class="page-header">
<h2 id="opening-a-connection">Opening a Connection</h2>
</div>
<p>To open a connection between a resource and a swarm, send an
HTTP <strong>POST</strong> request to the following URL with
the following headers.</p>
<h5 class="sub-header">URL:</h5>
<pre class="prettyprint language-javascript">
'http://api.bugswarm.net/stream?swarm_id=SWARM_ID&resource_id=RESOURCE_ID'
</pre>
<p>Replace <code>SWARM_ID</code> and <code>RESOURCE_ID</code>
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 <code>&swarm_id=SWARM_ID</code> statements to the
single <code>swarm_id=SWARM_ID</code> that is given above. Keep
in mind that a resource must be added to the swarm using the
Configuration API's <a href=
"restful_swarms.html#add-resource">Add Resource</a> method for
swarms before it may connect to the swarm and begin producing
and/or consuming.</p>
<h5 class="sub-header">Headers:</h5>
<ul class="unstyled">
<li><strong>x-bugswarmapikey:</strong> PARTICIPATION_KEY</li>
<li><strong>transfer-encoding:</strong> chunked</li>
<li><strong>connection:</strong> keep-alive</li>
</ul>
<p><strong>Note</strong> 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.</p>
<div class="page-header"></div><br>
<br>
<div class="page-header">
<h2 id="sending-messages">Sending Messages</h2>
</div>
<p>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.</p>
<ul>
<li>
<h4 class="sub-header">Chunked Encoding</h4>
</li>
<li style="list-style: none; display: inline">
<p>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 <a href=
"http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html">this
page</a> as well as <a href=
"http://en.wikipedia.org/wiki/Chunked_transfer_encoding#Format">
Wikipedia</a>.</p>
</li>
<li>
<h4 class="sub-header">Formats</h4>
</li>
<li style="list-style: none">
<strong>Public message to all swarms the resource is
connected to:</strong><br>
<br>
<pre class="prettyprint language-javascript">
{"message": {"payload": {"x":1}}}
</pre><strong>Public message to specific swarm(s):</strong><br>
<br>
<pre class="prettyprint language-javascript">
{"message": {"to": ["234", "123"], "payload": {"x":1}}}
</pre><strong>Private message to specific resource in specific
swarm:</strong><br>
<br>
<pre class="prettyprint language-javascript">
{"message": {"to": [{"swarm": "234", "resource": "222"}], "payload": {"y":2}}}
</pre>
<p><strong>Note</strong> that, within the message, the
<strong>payload</strong> itself must also be a <strong>JSON
object or JSON array</strong> .</p>
<div class="page-header"></div><br>
<br>
<div class="page-header">
<h2 id="receiving-messages">Receiving Messages</h2>
</div>
<p>Messages will be received in the following formats
depending on whether they are public or private.</p><br>
<strong>Public message received from resource 123 as
observed by all resources connected to the
swarm.</strong><br>
<br>
<pre class="prettyprint language-javascript">
{"message": {"from": {"swarm": "234", "resource":"123"}, "public": true, "payload": {"x": 1}}}
</pre><strong>Private mesage recieved from resource 123 as observed
by the receiving resource.</strong><br>
<br>
<pre class="prettyprint language-javascript">
{"message": {"from": {"swarm": "234", resource: "123"}, "public": false, "payload": {"y": 2}}}
</pre>
<div class="page-header"></div><br>
<br>
<div class="page-header">
<h2 id="presence-and-errors">Presence and Errors</h2>
</div>
<div class="row">
<div class="span8 columns">
<h3>Presence Notifications</h3>
<ul>
<li>
<h5 class="sub-header">Swarm Presence</h5>
</li>
<li style="list-style: none; display: inline">
<p>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.</p>
</li>
<li>
<h5 class="sub-header">Direct Presence</h5>
</li>
<li style="list-style: none; display: inline">
<p>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.</p>
</li>
</ul>
</div>
<div class="span8 columns">
<h3>Errors</h3>
<p>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.</p>
</div>
</div>
<div class="page-header"></div>
<h3>Formats</h3>
<h4 class="sub-header">Presence Notifications</h4>
<div class="row">
<div class="span8 columns">
<ul>
<li>
<h5>Sender</h5>
</li>
<li style="list-style: none">To join swarms 234 and
333:<br>
<br>
<pre class="prettyprint language-javascript">
{"presence": {"to": ["234", "333"]}}
</pre>To leave swarms 234 and 333:<br>
<br>
<pre class="prettyprint language-javascript">
{"presence": {"to": ["234", "333"], type: "unavailable"}}
</pre>
</li>
</ul>
</div>
<div class="span8 columns">
<ul>
<li>
<h5>Recipient</h5>
</li>
<li style="list-style: none">When resource 222 has
joined swarm 234:<br>
<br>
<pre class="prettyprint language-javascript">
{"presence": {"from": {"swarm": "234", "resource": "222", "user": "c4milo"}}
</pre>When resource 222 has left swarm 234:<br>
<br>
<pre class="prettyprint language-javascript">
{"presence": {"from": {"swarm": "234", "resource": "222", "user": "c4milo"}, "type": "unavailable"}
</pre>When a resource that is owned by the same user connects to
BUGswarm:<br>
<br>
<pre class="prettyprint language-javascript">
{"presence": {"from": {"resource": "222"}}}
</pre>When a resource that is owned by the same user disconnects
from BUGswarm:<br>
<br>
<pre class="prettyprint language-javascript">
{"presence": {"from": {"resource": "222"} "type": "unavailable"}}
</pre>
</li>
</ul>
</div>
</div>
<div class="page-header"></div>
<h4 class="sub-header">Errors</h4>
<ul>
<li>
<h5>Recipient</h5>
</li>
</ul>When an error occurs:<br>
<br>
<pre class="prettyprint language-javascript">
{"errors": [{"code": "xxx", description: "foo"}, {"code": "yyy", "description": "bar"}]}
</pre>
</li>
</ul>
</div>
</body>
</html>