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
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../img/favicon.ico">
<title>Overview & Endpoints - BBJ</title>
<link href="../css/bootstrap-custom.min.css" rel="stylesheet">
<link href="../css/font-awesome-4.5.0.css" rel="stylesheet">
<link href="../css/base.css" rel="stylesheet">
<link rel="stylesheet" href="../css/highlight.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script src="../js/jquery-1.10.2.min.js"></script>
<script src="../js/bootstrap-3.0.3.min.js"></script>
<script src="../js/highlight.pack.js"></script>
</head>
<body>
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="..">BBJ</a>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li >
<a href="..">Home</a>
</li>
<li class="dropdown active">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API <b class="caret"></b></a>
<ul class="dropdown-menu">
<li class="active">
<a href="./">Overview & Endpoints</a>
</li>
<li >
<a href="../errors/">Errors</a>
</li>
<li >
<a href="../validation/">Input Validation</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li >
<a rel="next" href="..">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li >
<a rel="prev" href="../errors/">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
<ul class="nav bs-sidenav">
<li class="main active"><a href="#how-to-bbj">How to BBJ?</a></li>
<li><a href="#input">Input</a></li>
<li><a href="#output">Output</a></li>
<li class="main "><a href="#authorization">Authorization</a></li>
<li><a href="#check_auth">check_auth</a></li>
<li class="main "><a href="#threads-messages">Threads & Messages</a></li>
<li><a href="#delete_post">delete_post</a></li>
<li><a href="#edit_post">edit_post</a></li>
<li><a href="#edit_query">edit_query</a></li>
<li><a href="#message_feed">message_feed</a></li>
<li><a href="#set_post_raw">set_post_raw</a></li>
<li><a href="#set_thread_pin">set_thread_pin</a></li>
<li><a href="#thread_create">thread_create</a></li>
<li><a href="#thread_index">thread_index</a></li>
<li><a href="#thread_load">thread_load</a></li>
<li><a href="#thread_reply">thread_reply</a></li>
<li class="main "><a href="#tools">Tools</a></li>
<li><a href="#db_validate">db_validate</a></li>
<li><a href="#format_message">format_message</a></li>
<li><a href="#user_map">user_map</a></li>
<li class="main "><a href="#users">Users</a></li>
<li><a href="#get_me">get_me</a></li>
<li><a href="#is_admin">is_admin</a></li>
<li><a href="#user_get">user_get</a></li>
<li><a href="#user_is_registered">user_is_registered</a></li>
<li><a href="#user_register">user_register</a></li>
<li><a href="#user_update">user_update</a></li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<h1 id="how-to-bbj">How to BBJ?</h1>
<h2 id="input">Input</h2>
<p>BBJ is interacted with entirely through POST requests, whose bodies are
json objects.</p>
<p>The endpoints, all listed below, can be contacted at the path /api/ relative
to the root of where BBJ is hosted. If bbj is hosted on a server on port 80
at the root:</p>
<p><code>http://server.com/api/endpoint_here</code></p>
<p>The body of your request contains all of it's argument fields, instead of
using URL parameters. As a demonstration, to call <code>thread_create</code>,
it requires two arguments: <code>title</code>, and <code>body</code>. We put those argument
names at the root of the json object, and their values are the info
passed into the API for that spot. Your input will look like this:</p>
<pre><code class="json">{
"title": "Hello world!!",
"body": "Hi! I am exploring this cool board thing!!"
}
</code></pre>
<p>And you will POST this body to <code>http://server.com:PORT/api/thread_create</code>.</p>
<p>A few endpoints do not require any arguments. These can still be POSTed to,
but the body may be completely empty or an empty json object. You can even
GET these if you so choose.</p>
<p>For all endpoints, argument keys that are not consumed by the endpoint are
ignored. Posting an object with a key/value pair of <code>"sandwich": True</code> will
not clog up any pipes :) In the same vein, endpoints who dont take arguments
don't care if you supply them anyway.</p>
<h2 id="output">Output</h2>
<p>BBJ returns data in a consistently formatted json object. The base object
has three keys: <code>data</code>, <code>usermap</code>, and <code>error</code>. Visualizied:</p>
<pre><code class="javascript">{
"error": false, // boolean false or error object
"data": null, // null or the requested data from endpoint.
"usermap": {} // potentially empty object, maps user_ids to user objects
}
// If "error" is true, it looks like this:
{
"error": {
"code": // an integer from 0 to 5,
"description": // a string describing the error in detail.
}
"data": null // ALWAYS null if error is not false
"usermap": {} // ALWAYS empty if error is not false
}
</code></pre>
<h3 id="data">data</h3>
<p><code>data</code> is what the endpoint actually returns. The type of contents vary
by endpoint and are documented below. If an endpoint says it returns a
boolean, it will look like <code>"data": True</code>. If it says it returns an array,
it will look like <code>"data": ["stuff", "goes", "here"]</code></p>
<h3 id="usermap">usermap</h3>
<p>The usermap is a json object mapping user_ids within <code>data</code> to full user
objects. BBJ handles users entirely by an ID system, meaning any references
to them inside of response data will not include vital information like their
username, or their profile information. Instead, we fetch those values from
this usermap object. All of it's root keys are user_id's and their values
are user objects. It should be noted that the anonymous user has it's own
ID and profile object as well.</p>
<h3 id="error">error</h3>
<p><code>error</code> is typically <code>false</code>. If it is <strong>not</strong> false, then the request failed
and the json object that <code>error</code> contains should be inspected. (see the above
visualation) Errors follow a strict code system, making it easy for your client
to map these responses to native exception types or signals in your language of
choice. See <a href="../errors/">the full error page</a> for details.</p>
<p><br><br></p>
<h1 id="authorization">Authorization</h1>
<hr />
<p>See also <a href="authorization.md">the Authorization page</a>.</p>
<h2 id="check_auth">check_auth</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>target_user</strong>: string: either a user_name or a user_id</p>
</li>
<li>
<p><strong>target_hash</strong>: string: sha256 hash for the password to check</p>
</li>
</ul>
<p>Returns boolean <code>true</code> or <code>false</code> of whether the hash given
is correct for the given user.</p>
<p><br>
<br><br></p>
<h1 id="threads-messages">Threads & Messages</h1>
<hr />
<h2 id="delete_post">delete_post</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>thread_id</strong>: string: the id of the thread this message was posted in.</p>
</li>
<li>
<p><strong>post_id</strong>: integer: the id of the target message.</p>
</li>
</ul>
<p>Requires the arguments <code>thread_id</code> and <code>post_id</code>.</p>
<p>Delete a message from a thread. The same rules apply
here as <code>edit_post</code> and <code>edit_query</code>: the logged in user
must either be the one who posted the message within 24hrs,
or have admin rights. The same error descriptions and code
are returned on falilure. Boolean true is returned on
success.</p>
<p>If the post_id is 0, the whole thread is deleted.</p>
<p><br></p>
<h2 id="edit_post">edit_post</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>thread_id</strong>: string: the thread the message was posted in.</p>
</li>
<li>
<p><strong>post_id</strong>: integer: the target post_id to edit.</p>
</li>
<li>
<p><strong>body</strong>: string: the new message body.</p>
</li>
<li>
<p><strong>OPTIONAL: send_raw</strong>: boolean: set the formatting mode for the target message.</p>
</li>
</ul>
<p>Replace a post with a new body. Requires the arguments
<code>thread_id</code>, <code>post_id</code>, and <code>body</code>. This method verifies
that the user can edit a post before commiting the change,
otherwise an error object is returned whose description
should be shown to the user.</p>
<p>To perform sanity checks and retrieve the unformatted body
of a post without actually attempting to replace it, use
<code>edit_query</code> first.</p>
<p>Optionally you may also include the argument <code>send_raw</code> to
set the message's formatting flag. However, if this is the
only change you would like to make, you should use the
endpoint <code>set_post_raw</code> instead.</p>
<p>Returns the new message object.</p>
<p><br></p>
<h2 id="edit_query">edit_query</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>thread_id</strong>: string: the id of the thread the message was posted in.</p>
</li>
<li>
<p><strong>post_id</strong>: integer: the id of the target message.</p>
</li>
</ul>
<p>Queries the database to ensure the user can edit a given
message. Requires the arguments <code>thread_id</code> and <code>post_id</code>
(does not require a new body)</p>
<p>Returns the original message object without any formatting
on success. Returns a descriptive code 4 otherwise.</p>
<p><br></p>
<h2 id="message_feed">message_feed</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>time</strong>: int/float: epoch/unix time of the earliest point of interest</p>
</li>
<li>
<p><strong>OPTIONAL: format</strong>: string: the specifier for the desired formatting engine</p>
</li>
</ul>
<p>Returns a special object representing all activity on the board since <code>time</code>.</p>
<pre><code class="javascript">{
"threads": {
"thread_id": {
// ...thread object
},
// ...more thread_id/object pairs
},
"messages": [
...standard message object array sorted by date
]
}
</code></pre>
<p>The message objects in <code>messages</code> are the same objects returned
in threads normally. They each have a thread_id parameter, and
you can access metadata for these threads by the <code>threads</code> object
which is also provided.</p>
<p>The <code>messages</code> array is already sorted by submission time, newest
first. The order in the threads object is undefined and you should
instead use their <code>last_mod</code> attribute if you intend to list them
out visually.</p>
<p><br></p>
<h2 id="set_post_raw">set_post_raw</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>thread_id</strong>: string: the id of the thread the message was posted in.</p>
</li>
<li>
<p><strong>post_id</strong>: integer: the id of the target message.</p>
</li>
<li>
<p><strong>value</strong>: boolean: the new <code>send_raw</code> value to apply to the message.</p>
</li>
</ul>
<p>Requires the boolean argument of <code>value</code>, string argument
<code>thread_id</code>, and integer argument <code>post_id</code>. <code>value</code>, when false,
means that the message will be passed through message formatters
before being sent to clients. When <code>value</code> is true, this means
it will never go through formatters, all of its whitespace is
sent to clients verbatim and expressions are not processed.</p>
<p>The same rules for editing messages (see <code>edit_query</code>) apply here
and the same error objects are returned for violations.</p>
<p>You may optionally set this value as well when using <code>edit_post</code>,
but if this is the only change you want to make to the message,
using this endpoint instead is preferable.</p>
<p><br></p>
<h2 id="set_thread_pin">set_thread_pin</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>thread_id</strong>: string: the id of the thread to modify.</p>
</li>
<li>
<p><strong>value</strong>: boolean: <code>true</code> to pin thread, <code>false</code> otherwise.</p>
</li>
</ul>
<p>Requires the arguments <code>thread_id</code> and <code>value</code>. <code>value</code>
must be a boolean of what the pinned status should be.
This method requires that the caller is logged in and
has admin status on their account.</p>
<p>Returns the same boolean you supply as <code>value</code></p>
<p><br></p>
<h2 id="thread_create">thread_create</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>body</strong>: string: The body of the first message</p>
</li>
<li>
<p><strong>title</strong>: string: The title name for this thread</p>
</li>
<li>
<p><strong>OPTIONAL: send_raw</strong>: boolean: formatting mode for the first message.</p>
</li>
</ul>
<p>Creates a new thread and returns it. Requires the non-empty
string arguments <code>body</code> and <code>title</code>.</p>
<p>If the argument <code>send_raw</code> is specified and has a non-nil
value, the OP message will never recieve special formatting.</p>
<p><br></p>
<h2 id="thread_index">thread_index</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>OPTIONAL: include_op</strong>: boolean: Include a <code>messages</code> object containing the original post</li>
</ul>
<p>Return an array with all the server's threads. They are already sorted for
you; most recently modified threads are at the beginning of the array.
Unless you supply <code>include_op</code>, these threads have no <code>messages</code> parameter.
If you do, the <code>messages</code> parameter is an array with a single message object
for the original post.</p>
<p><br></p>
<h2 id="thread_load">thread_load</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>thread_id</strong>: string: the thread to load.</p>
</li>
<li>
<p><strong>OPTIONAL: op_only</strong>: boolean: include only the original message in <code>messages</code></p>
</li>
<li>
<p><strong>OPTIONAL: format</strong>: string: the formatting type of the returned messages.</p>
</li>
</ul>
<p>Returns the thread object with all of its messages loaded.
Requires the argument <code>thread_id</code>. <code>format</code> may also be
specified as a formatter to run the messages through.
Currently only "sequential" is supported.</p>
<p>You may also supply the parameter <code>op_only</code>. When it's value
is non-nil, the messages array will only include post_id 0 (the first)</p>
<p><br></p>
<h2 id="thread_reply">thread_reply</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>thread_id</strong>: string: the id for the thread this message should post to.</p>
</li>
<li>
<p><strong>body</strong>: string: the message's body of text.</p>
</li>
<li>
<p><strong>OPTIONAL: send_raw</strong>: boolean: formatting mode for the posted message.</p>
</li>
</ul>
<p>Creates a new reply for the given thread and returns it.
Requires the string arguments <code>thread_id</code> and <code>body</code></p>
<p>If the argument <code>send_raw</code> is specified and has a non-nil
value, the message will never recieve special formatting.</p>
<p><br>
<br><br></p>
<h1 id="tools">Tools</h1>
<hr />
<h2 id="db_validate">db_validate</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>key</strong>: string: the identifier for the ruleset to check.</p>
</li>
<li>
<p><strong>value</strong>: VARIES: the object for which <code>key</code> will check for.</p>
</li>
<li>
<p><strong>OPTIONAL: error</strong>: boolean: when <code>true</code>, will return an API error response instead of a special object.</p>
</li>
</ul>
<p>See also <a href="../validation/">the Input Validation page</a>.</p>
<p>Requires the arguments <code>key</code> and <code>value</code>. Returns an object
with information about the database sanity criteria for
key. This can be used to validate user input in the client
before trying to send it to the server.</p>
<p>If the argument <code>error</code> is supplied with a non-nil value,
the server will return a standard error object on failure
instead of the special object described below.</p>
<p>The returned object has two keys:</p>
<p>{
"bool": true/false,
"description": null/"why this value is bad"
}</p>
<p>If bool == false, description is a string describing the
problem. If bool == true, description is null and the
provided value is safe to use.</p>
<p><br></p>
<h2 id="format_message">format_message</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>body</strong>: string: the message body to apply formatting to.</p>
</li>
<li>
<p><strong>format</strong>: string: the specifier for the desired formatting engine</p>
</li>
</ul>
<p>Requires the arguments <code>body</code> and <code>format</code>. Applies
<code>format</code> to <code>body</code> and returns the new object. See
<code>thread_load</code> for supported specifications for <code>format</code>.</p>
<p><br></p>
<h2 id="user_map">user_map</h2>
<p><em>requires no arguments</em></p>
<p>Returns an array with all registered user_ids, with the usermap
object populated by their full objects. This method is <em>NEVER</em>
neccesary when using other endpoints, as the usermap returned
on those requests already contains all the information you will
need. This endpoint is useful for statistic purposes only.</p>
<p><br>
<br><br></p>
<h1 id="users">Users</h1>
<hr />
<h2 id="get_me">get_me</h2>
<p><em>requires no arguments</em></p>
<p>Requires no arguments. Returns your internal user object,
including your <code>auth_hash</code>.</p>
<p><br></p>
<h2 id="is_admin">is_admin</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>target_user</strong>: string: user_id or user_name to check against.</li>
</ul>
<p>Requires the argument <code>target_user</code>. Returns a boolean
of whether that user is an admin.</p>
<p><br></p>
<h2 id="user_get">user_get</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul>
<p>Returns a user object for the given target.</p>
<p><br></p>
<h2 id="user_is_registered">user_is_registered</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul>
<p>Returns boolean <code>true</code> or <code>false</code> of whether the given target is
registered on the server.</p>
<p><br></p>
<h2 id="user_register">user_register</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>user_name</strong>: string: the desired display name</p>
</li>
<li>
<p><strong>auth_hash</strong>: string: a sha256 hash of a password</p>
</li>
</ul>
<p>Register a new user into the system and return the new user object
on success. The returned object includes the same <code>user_name</code> and
<code>auth_hash</code> that you supply, in addition to all the default user
parameters. Returns code 4 errors for any failures.</p>
<p><br></p>
<h2 id="user_update">user_update</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li>
<p><strong>Any of the following may be submitted</strong>: </p>
</li>
<li>
<p><strong>user_name</strong>: string: a desired display name</p>
</li>
<li>
<p><strong>auth_hash</strong>: string: sha256 hash for a new password</p>
</li>
<li>
<p><strong>quip</strong>: string: a short string that can be used as a signature</p>
</li>
<li>
<p><strong>bio</strong>: string: a user biography for their profile</p>
</li>
<li>
<p><strong>color</strong>: integer: 0-6, a display color for the user</p>
</li>
</ul>
<p>Receives new parameters and assigns them to the user object.
This method requires that you send a valid User/Auth header
pair with your request, and the changes are made to that
account.</p>
<p>Take care to keep your client's User/Auth header pair up to date
after using this method.</p>
<p>The newly updated user object is returned on success,
including the <code>auth_hash</code>.</p>
<p><br></p></div>
</div>
<footer class="col-md-12">
<hr>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script>var base_url = '..';</script>
<script data-main="../mkdocs/js/search.js" src="../mkdocs/js/require.js"></script>
<script src="../js/base.js"></script><div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="Search Modal" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">×</span><span class="sr-only">Close</span></button>
<h4 class="modal-title" id="exampleModalLabel">Search</h4>
</div>
<div class="modal-body">
<p>
From here you can search these documents. Enter
your search terms below.
</p>
<form role="form">
<div class="form-group">
<input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query">
</div>
</form>
<div id="mkdocs-search-results"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
|