magical
/
bbj
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

more doc changes

pull/4/head
Blake DeMarcy 2017-05-03 21:35:47 -05:00
parent b313e4b987
commit dc1694e0f4
10 changed files with 443 additions and 315 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

225
documentation/docs/api_overview.md
View File

@ -86,14 +86,16 @@ to map these responses to native exception types or signals in your language of
choice. See [the full error page](errors.md) for details.
<br><br>
# Authorization
------
## check_auth
### Args:
**target_user**: string: either a user_name or a user_id
**Arguments:**
**target_hash**: string: sha256 hash for the password to check
* __target_user__: string: either a user_name or a user_id
* __target_hash__: string: sha256 hash for the password to check
@ -101,17 +103,17 @@ Takes the arguments `target_user` and `target_hash`, and
returns boolean true or false whether the hash is valid.
--------
<br>
<br><br>
# Threads & Messages
------
## delete_post
### Args:
**thread_id**: string: the id of the thread this message was posted in.
**Arguments:**
**post_id**: integer: the id of the target message.
* __thread_id__: string: the id of the thread this message was posted in.
* __post_id__: integer: the id of the target message.
@ -126,16 +128,19 @@ success.
If the post_id is 0, the whole thread is deleted.
<br>
## edit_post
### Args:
**thread_id**: string: the thread the message was posted in.
**Arguments:**
**post_id**: integer: the target post_id to edit.
* __thread_id__: string: the thread the message was posted in.
**body**: string: the new message body.
* __post_id__: integer: the target post_id to edit.
**OPTIONAL: send_raw**: boolean: set the formatting mode for the target message.
* __body__: string: the new message body.
* __OPTIONAL: send_raw__: boolean: set the formatting mode for the target message.
@ -156,12 +161,15 @@ endpoint `set_post_raw` instead.
Returns the new message object.
<br>
## edit_query
### Args:
**thread_id**: string: the id of the thread the message was posted in.
**Arguments:**
**post_id**: integer: the id of the target message.
* __thread_id__: string: the id of the thread the message was posted in.
* __post_id__: integer: the id of the target message.
@ -172,10 +180,13 @@ message. Requires the arguments `thread_id` and `post_id`
Returns the original message object without any formatting
on success. Returns a descriptive code 4 otherwise.
<br>
## message_feed
### Args:
**time**: int/float: epoch/unix time of the earliest point of interest
**Arguments:**
* __time__: int/float: epoch/unix time of the earliest point of interest
@ -206,14 +217,17 @@ You may optionally provide a `format` argument: this is treated
the same way as the `thread_load` endpoint and you should refer
to its documentation for more info.
<br>
## set_post_raw
### Args:
**thread_id**: string: the id of the thread the message was posted in.
**Arguments:**
**post_id**: integer: the id of the target message.
* __thread_id__: string: the id of the thread the message was posted in.
**value**: boolean: the new `send_raw` value to apply to the message.
* __post_id__: integer: the id of the target message.
* __value__: boolean: the new `send_raw` value to apply to the message.
@ -231,12 +245,15 @@ You may optionally set this value as well when using `edit_post`,
but if this is the only change you want to make to the message,
using this endpoint instead is preferable.
<br>
## set_thread_pin
### Args:
**thread_id**: string: the id of the thread to modify.
**Arguments:**
**value**: boolean: `true` to pin thread, `false` otherwise.
* __thread_id__: string: the id of the thread to modify.
* __value__: boolean: `true` to pin thread, `false` otherwise.
@ -247,14 +264,17 @@ has admin status on their account.
Returns the same boolean you supply as `value`
<br>
## thread_create
### Args:
**body**: string: The body of the first message
**Arguments:**
**title**: string: The title name for this thread
* __body__: string: The body of the first message
**OPTIONAL: send_raw**: boolean: formatting mode for the first message.
* __title__: string: The title name for this thread
* __OPTIONAL: send_raw__: boolean: formatting mode for the first message.
@ -264,10 +284,13 @@ string arguments `body` and `title`.
If the argument `send_raw` is specified and has a non-nil
value, the OP message will never recieve special formatting.
<br>
## thread_index
### Args:
**OPTIONAL: include_op**: boolean: Include a `messages` object with the original post
**Arguments:**
* __OPTIONAL: include_op__: boolean: Include a `messages` object with the original post
@ -278,14 +301,17 @@ Optionally, you may supply the argument `include_op`, which, when
non-nil, will include a "messages" key with the object, whose sole
content is the original message (post_id 0).
<br>
## thread_load
### Args:
**thread_id**: string: the thread to load.
**Arguments:**
**OPTIONAL: op_only**: boolean: include only the original message in `messages`
* __thread_id__: string: the thread to load.
**OPTIONAL: format**: string: the formatting type of the returned messages.
* __OPTIONAL: op_only__: boolean: include only the original message in `messages`
* __OPTIONAL: format__: string: the formatting type of the returned messages.
@ -297,14 +323,17 @@ Currently only "sequential" is supported.
You may also supply the parameter `op_only`. When it's value
is non-nil, the messages array will only include post_id 0 (the first)
<br>
## thread_reply
### Args:
**thread_id**: string: the id for the thread this message should post to.
**Arguments:**
**body**: string: the message's body of text.
* __thread_id__: string: the id for the thread this message should post to.
**OPTIONAL: send_raw**: boolean: formatting mode for the posted message.
* __body__: string: the message's body of text.
* __OPTIONAL: send_raw__: boolean: formatting mode for the posted message.
@ -315,19 +344,19 @@ If the argument `send_raw` is specified and has a non-nil
value, the message will never recieve special formatting.
--------
<br>
<br><br>
# Tools
------
## db_validate
### Args:
**key**: string: the identifier for the ruleset to check.
**Arguments:**
**value**: VARIES: the object for which `key` will check for.
* __key__: string: the identifier for the ruleset to check.
**OPTIONAL: error**: boolean: when `true`, will return an API error response instead of a special object.
* __value__: VARIES: the object for which `key` will check for.
* __OPTIONAL: error__: boolean: when `true`, will return an API error response instead of a special object.
@ -351,12 +380,15 @@ If bool == false, description is a string describing the
problem. If bool == true, description is null and the
provided value is safe to use.
<br>
## format_message
### Args:
**body**: string: the message body to apply formatting to.
**Arguments:**
**format**: string: the specifier for the desired formatting engine
* __body__: string: the message body to apply formatting to.
* __format__: string: the specifier for the desired formatting engine
@ -364,96 +396,113 @@ Requires the arguments `body` and `format`. Applies
`format` to `body` and returns the new object. See
`thread_load` for supported specifications for `format`.
<br>
## user_map
### Args:
__No arguments__
_requires no arguments_
Returns an array with all registered user_ids, with the usermap
object populated by their full objects.
--------
<br>
<br><br>
# Users
------
## get_me
### Args:
__No arguments__
_requires no arguments_
Requires no arguments. Returns your internal user object,
including your authorization hash.
<br>
## is_admin
### Args:
**target_user**: string: user_id or user_name to check against.
**Arguments:**
* __target_user__: string: user_id or user_name to check against.
Requires the argument `target_user`. Returns a boolean
of whether that user is an admin.
<br>
## user_get
### Args:
**target_user**: string: either a user_name or a user_id
**Arguments:**
* __target_user__: string: either a user_name or a user_id
Retreive an external user object for the given `target_user`.
Can be a user_id or user_name.
<br>
## user_is_registered
### Args:
**target_user**: string: either a user_name or a user_id
**Arguments:**
* __target_user__: string: either a user_name or a user_id
Takes the argument `target_user` and returns true or false
whether they are in the system or not.
<br>
## user_register
### Args:
**user_name**: string: the desired display name
**Arguments:**
**auth_hash**: string: a sha256 hash of a password
* __user_name__: string: the desired display name
* __auth_hash__: string: a sha256 hash of a password
Register a new user into the system and return the new object.
Requires the string arguments `user_name` and `auth_hash`.
Do not send User/Auth headers with this method.
Register a new user into the system and return the new user object
on success. The returned object includes the same `user_name` and
`auth_hash` that you supply, in addition to all the default user
parameters. Returns code 4 errors for any failures.
<br>
## user_update
### Args:
**Any of the following may be submitted:**:
**Arguments:**
**user_name**: string: a desired display name
* __Any of the following may be submitted__:
**auth_hash**: string: sha256 hash for a new password
* __user_name__: string: a desired display name
**quip**: string: a short string that can be used as a signature
* __auth_hash__: string: sha256 hash for a new password
**bio**: string: a user biography for their profile
* __quip__: string: a short string that can be used as a signature
**color**: integer: 0-6, a display color for the user
* __bio__: string: a user biography for their profile
* __color__: integer: 0-6, a display color for the user
Receives new parameters and assigns them to the user_object
in the database. The following new parameters can be supplied:
`user_name`, `auth_hash`, `quip`, `bio`, and `color`. Any number
of them may be supplied.
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.
The newly updated user object is returned on success.
Take care to keep your client's User/Auth header pair up to date
after using this method.
The newly updated user object is returned on success,
including the `auth_hash`.
--------
<br>

33
documentation/docs/errors.md
View File

@ -1,10 +1,12 @@
Errors in BBJ are separated into 6 different codes to help
ease handling a little bit. Errors are all or nothing, there
are no "warnings". If a response has a non-false error field,
then data will always be null. An error response from the api
looks like this...
## Handling Error Responses
```
Errors in BBJ are separated into 6 different codes, to allow easy mapping to
native exception and signaling systems available in the client's programming
language. Errors are all or nothing, there are no "warnings". If a response has
a non-false error field, then data will always be null. An error response from
the api looks like this...
```javascript
{
"error": {
"code": // an integer from 0 to 5,
@ -15,13 +17,18 @@ looks like this...
}
```
The codes split errors into a few categories. Some are oriented
The codes split errors into categories. Some are oriented
to client developers while others should be shown directly to
users.
* 0: Malformed but non-empty json input. An empty json input where it is required is handled by code 3. This is just decoding errors. The exception text is returned as description.
* 1: Internal server error. A short representation of the internal exception as well as the code the server logged it as is returned in the description. Your clients cannot recover from this class of error, and its probably not your fault if you encounter it. If you ever get one, file a bug report.
* 2: Server HTTP error: This is similar to the above but captures errors for the HTTP server rather than BBJs own codebase. The description contains the HTTP error code and server description. This notably covers 404s and thus invalid endpoint names.
* 3: Parameter error: client sent erroneous input for its method. This could mean missing arguments, type errors, etc. It generalizes errors that should be fixed by the client developer and the returned descriptions are geared to them rather than end users.
* 4: User error: These errors regard actions that the user has taken that are invalid, but not really errors in a traditional sense. The description field should be shown to users verbatim, in a clear and noticeable fashion. They are formatted as concise English sentences and end with appropriate punctuation marks.
* 5: Authorization error: This code represents an erroneous User/Auth header pair. This should trigger the user to provide correct credentials or fall back to anon mode.
* **Code 0**: Malformed but non-empty json input. An empty json input where it is required is handled by code 3. This is just decoding errors. The exception text is returned as description.
* **Code 1**: Internal server error. A short representation of the internal exception as well as the code the server logged it as is returned in the description. Your clients cannot recover from this class of error, and its probably not your fault if you encounter it. If you ever get one, file a bug report.
* **Code 2**: Server HTTP error: This is similar to the above but captures errors for the HTTP server rather than BBJs own codebase. The description contains the HTTP error code and server description. This notably covers 404s and thus invalid endpoint names. The HTTP error code is left intact, so you may choose to let your HTTP library or tool of choice handle these for you.
* **Code 3**: Parameter error: client sent erroneous input for its method. This could mean missing arguments, type errors, etc. It generalizes errors that should be fixed by the client developer and the returned descriptions are geared to them rather than end users.
* **Code 4**: User error: These errors regard actions that the user has taken that are invalid, but not really errors in a traditional sense. The description field should be shown to users verbatim, in a clear and noticeable fashion. They are formatted as concise English sentences and end with appropriate punctuation marks.
* **Code 5**: Authorization error: This code represents an erroneous User/Auth header pair. This should trigger the user to provide correct credentials or fall back to anon mode.

14
documentation/docs/validation.md
View File

@ -1,6 +1,8 @@
## Implementing good sanity checks in your client.
The server has an endpoint called `db_validate`. What this does is take
a `key` and a `value` and compares `value` to a set of rules specified by
`key`. This is the same function used internally by the database to scan
a `key` and a `value` argument, and compares `value` to a set of rules specified by
`key`. This is the same function used internally by the database to check
values before committing them to the database. By default it returns a
descriptive object under `data`, but you can specify the key/value pair
`"error": True` to get a standard error response back. A standard call
@ -67,7 +69,6 @@ The following keys are currently available.
The descriptions returned are friendly, descriptive, and should be shown
directly to users
## Implementing good sanity checks in your client
By using this endpoint, you will never have to validate values in your
own code before sending them to the server. This means you can do things
@ -78,17 +79,16 @@ This is used in the elisp client when registering users and for the thread
title prompt which is shown before opening a composure window. The reason
for rejection is displayed clearly to the user and input window is restored.
```
```lisp
(defun bbj-sane-value (prompt key)
"Opens an input loop with the user, where the response is
passed to the server to check it for validity before the
user is allowed to continue. Will recurse until the input
is valid, then it is returned."
(let* ((value (read-from-minibuffer prompt))
(response (bbj-request! 'db_validate
'value value 'key key)))
(response (bbj-request! 'db_validate 'value value 'key key)))
(if (alist-get 'bool response)
value
value ;; return the user's input back to the caller
(message (alist-get 'description response))
(sit-for 2)
(bbj-sane-value prompt key))))

216
documentation/site/api_overview/index.html
View File

@ -189,19 +189,35 @@ and the json object that <code>error</code> contains should be inspected. (see t
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 />
<h2 id="check_auth">check_auth</h2>
<h3 id="args">Args:</h3>
<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>Takes the arguments <code>target_user</code> and <code>target_hash</code>, and
returns boolean true or false whether the hash is valid.</p>
<hr />
<p><br>
<br><br></p>
<h1 id="threads-messages">Threads &amp; Messages</h1>
<hr />
<h2 id="delete_post">delete_post</h2>
<h3 id="args_1">Args:</h3>
<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
@ -210,12 +226,23 @@ 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>
<h3 id="args_2">Args:</h3>
<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,
@ -229,18 +256,28 @@ 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>
<h3 id="args_3">Args:</h3>
<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>
<h3 id="args_4">Args:</h3>
<p><strong>time</strong>: int/float: epoch/unix time of the earliest point of interest</p>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>time</strong>: int/float: epoch/unix time of the earliest point of interest</li>
</ul>
<p>Returns a special object representing all activity on the board since
the argument <code>time</code>, a unix/epoch timestamp.</p>
<p>{
@ -263,11 +300,20 @@ out visually.</p>
<p>You may optionally provide a <code>format</code> argument: this is treated
the same way as the <code>thread_load</code> endpoint and you should refer
to its documentation for more info.</p>
<p><br></p>
<h2 id="set_post_raw">set_post_raw</h2>
<h3 id="args_5">Args:</h3>
<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
@ -279,59 +325,106 @@ 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>
<h3 id="args_6">Args:</h3>
<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>
<h3 id="args_7">Args:</h3>
<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>
<h3 id="args_8">Args:</h3>
<p><strong>OPTIONAL: include_op</strong>: boolean: Include a <code>messages</code> object with the original post</p>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>OPTIONAL: include_op</strong>: boolean: Include a <code>messages</code> object with the original post</li>
</ul>
<p>Return an array with all the threads, ordered by most recent activity.
Requires no arguments.</p>
<p>Optionally, you may supply the argument <code>include_op</code>, which, when
non-nil, will include a "messages" key with the object, whose sole
content is the original message (post_id 0).</p>
<p><br></p>
<h2 id="thread_load">thread_load</h2>
<h3 id="args_9">Args:</h3>
<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>
<h3 id="args_10">Args:</h3>
<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>
<hr />
<p><br>
<br><br></p>
<h1 id="tools">Tools</h1>
<hr />
<h2 id="db_validate">db_validate</h2>
<h3 id="args_11">Args:</h3>
<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>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
@ -347,61 +440,104 @@ instead of the special object described below.</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>
<h3 id="args_12">Args:</h3>
<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>
<h3 id="args_13">Args:</h3>
<p><strong>No arguments</strong></p>
<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.</p>
<hr />
<p><br>
<br><br></p>
<h1 id="users">Users</h1>
<hr />
<h2 id="get_me">get_me</h2>
<h3 id="args_14">Args:</h3>
<p><strong>No arguments</strong></p>
<p><em>requires no arguments</em></p>
<p>Requires no arguments. Returns your internal user object,
including your authorization hash.</p>
<p><br></p>
<h2 id="is_admin">is_admin</h2>
<h3 id="args_15">Args:</h3>
<p><strong>target_user</strong>: string: user_id or user_name to check against.</p>
<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>
<h3 id="args_16">Args:</h3>
<p><strong>target_user</strong>: string: either a user_name or a user_id</p>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul>
<p>Retreive an external user object for the given <code>target_user</code>.
Can be a user_id or user_name.</p>
<p><br></p>
<h2 id="user_is_registered">user_is_registered</h2>
<h3 id="args_17">Args:</h3>
<p><strong>target_user</strong>: string: either a user_name or a user_id</p>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul>
<p>Takes the argument <code>target_user</code> and returns true or false
whether they are in the system or not.</p>
<p><br></p>
<h2 id="user_register">user_register</h2>
<h3 id="args_18">Args:</h3>
<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>
<p>Register a new user into the system and return the new object.
Requires the string arguments <code>user_name</code> and <code>auth_hash</code>.
Do not send User/Auth headers with this method.</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>
<h3 id="args_19">Args:</h3>
<p><strong>Any of the following may be submitted:</strong>: </p>
<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>
<p>Receives new parameters and assigns them to the user_object
in the database. The following new parameters can be supplied:
<code>user_name</code>, <code>auth_hash</code>, <code>quip</code>, <code>bio</code>, and <code>color</code>. Any number
of them may be supplied.</p>
<p>The newly updated user object is returned on success.</p>
<hr /></div>
</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">

40
documentation/site/errors/index.html
View File

@ -91,16 +91,18 @@
<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="#handling-error-responses">Handling Error Responses</a></li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<p>Errors in BBJ are separated into 6 different codes to help
ease handling a little bit. Errors are all or nothing, there
are no "warnings". If a response has a non-false error field,
then data will always be null. An error response from the api
looks like this...</p>
<pre><code>{
<h2 id="handling-error-responses">Handling Error Responses</h2>
<p>Errors in BBJ are separated into 6 different codes, to allow easy mapping to
native exception and signaling systems available in the client's programming
language. Errors are all or nothing, there are no "warnings". If a response has
a non-false error field, then data will always be null. An error response from
the api looks like this...</p>
<pre><code class="javascript">{
&quot;error&quot;: {
&quot;code&quot;: // an integer from 0 to 5,
&quot;description&quot;: // a string describing the error in detail.
@ -110,16 +112,28 @@ looks like this...</p>
}
</code></pre>
<p>The codes split errors into a few categories. Some are oriented
<p>The codes split errors into categories. Some are oriented
to client developers while others should be shown directly to
users.</p>
<ul>
<li>0: Malformed but non-empty json input. An empty json input where it is required is handled by code 3. This is just decoding errors. The exception text is returned as description.</li>
<li>1: Internal server error. A short representation of the internal exception as well as the code the server logged it as is returned in the description. Your clients cannot recover from this class of error, and its probably not your fault if you encounter it. If you ever get one, file a bug report.</li>
<li>2: Server HTTP error: This is similar to the above but captures errors for the HTTP server rather than BBJs own codebase. The description contains the HTTP error code and server description. This notably covers 404s and thus invalid endpoint names.</li>
<li>3: Parameter error: client sent erroneous input for its method. This could mean missing arguments, type errors, etc. It generalizes errors that should be fixed by the client developer and the returned descriptions are geared to them rather than end users.</li>
<li>4: User error: These errors regard actions that the user has taken that are invalid, but not really errors in a traditional sense. The description field should be shown to users verbatim, in a clear and noticeable fashion. They are formatted as concise English sentences and end with appropriate punctuation marks.</li>
<li>5: Authorization error: This code represents an erroneous User/Auth header pair. This should trigger the user to provide correct credentials or fall back to anon mode.</li>
<li>
<p><strong>Code 0</strong>: Malformed but non-empty json input. An empty json input where it is required is handled by code 3. This is just decoding errors. The exception text is returned as description.</p>
</li>
<li>
<p><strong>Code 1</strong>: Internal server error. A short representation of the internal exception as well as the code the server logged it as is returned in the description. Your clients cannot recover from this class of error, and its probably not your fault if you encounter it. If you ever get one, file a bug report.</p>
</li>
<li>
<p><strong>Code 2</strong>: Server HTTP error: This is similar to the above but captures errors for the HTTP server rather than BBJs own codebase. The description contains the HTTP error code and server description. This notably covers 404s and thus invalid endpoint names. The HTTP error code is left intact, so you may choose to let your HTTP library or tool of choice handle these for you.</p>
</li>
<li>
<p><strong>Code 3</strong>: Parameter error: client sent erroneous input for its method. This could mean missing arguments, type errors, etc. It generalizes errors that should be fixed by the client developer and the returned descriptions are geared to them rather than end users.</p>
</li>
<li>
<p><strong>Code 4</strong>: User error: These errors regard actions that the user has taken that are invalid, but not really errors in a traditional sense. The description field should be shown to users verbatim, in a clear and noticeable fashion. They are formatted as concise English sentences and end with appropriate punctuation marks.</p>
</li>
<li>
<p><strong>Code 5</strong>: Authorization error: This code represents an erroneous User/Auth header pair. This should trigger the user to provide correct credentials or fall back to anon mode.</p>
</li>
</ul></div>
</div>

155
documentation/site/mkdocs/search_index.json
View File

File diff suppressed because one or more lines are too long

15
documentation/site/validation/index.html
View File

@ -91,14 +91,15 @@
<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="#implementing-good-sanity-checks-in-your-client">Implementing good sanity checks in your client</a></li>
<li class="main active"><a href="#implementing-good-sanity-checks-in-your-client">Implementing good sanity checks in your client.</a></li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<h2 id="implementing-good-sanity-checks-in-your-client">Implementing good sanity checks in your client.</h2>
<p>The server has an endpoint called <code>db_validate</code>. What this does is take
a <code>key</code> and a <code>value</code> and compares <code>value</code> to a set of rules specified by
<code>key</code>. This is the same function used internally by the database to scan
a <code>key</code> and a <code>value</code> argument, and compares <code>value</code> to a set of rules specified by
<code>key</code>. This is the same function used internally by the database to check
values before committing them to the database. By default it returns a
descriptive object under <code>data</code>, but you can specify the key/value pair
<code>"error": True</code> to get a standard error response back. A standard call
@ -156,7 +157,6 @@ to <code>db_validate</code> will look like this.</p>
</ul>
<p>The descriptions returned are friendly, descriptive, and should be shown
directly to users</p>
<h2 id="implementing-good-sanity-checks-in-your-client">Implementing good sanity checks in your client</h2>
<p>By using this endpoint, you will never have to validate values in your
own code before sending them to the server. This means you can do things
like implement an interactive prompt which will not allow the user to
@ -164,16 +164,15 @@ submit it unless the value is correct.</p>
<p>This is used in the elisp client when registering users and for the thread
title prompt which is shown before opening a composure window. The reason
for rejection is displayed clearly to the user and input window is restored.</p>
<pre><code>(defun bbj-sane-value (prompt key)
<pre><code class="lisp">(defun bbj-sane-value (prompt key)
&quot;Opens an input loop with the user, where the response is
passed to the server to check it for validity before the
user is allowed to continue. Will recurse until the input
is valid, then it is returned.&quot;
(let* ((value (read-from-minibuffer prompt))
(response (bbj-request! 'db_validate
'value value 'key key)))
(response (bbj-request! 'db_validate 'value value 'key key)))
(if (alist-get 'bool response)
value
value ;; return the user's input back to the caller
(message (alist-get 'description response))
(sit-for 2)
(bbj-sane-value prompt key))))

9
gendocs.sh 100755
View File

@ -0,0 +1,9 @@
#!/bin/sh
# Generate the documentation site.
# Invoke with no arguments in the base repo directory.
# Nothing magical here.
python3 ./mkendpoints.py
cd ./documentation
mkdocs build
cd ..

13
document_endpoints.py → mkendpoints.py
View File

@ -115,18 +115,19 @@ for function in endpoints:
types[function.doctype].append(function)
for doctype in sorted(types.keys()):
body += "# %s\n\n" % doctype
body += "<br><br>\n# %s\n------\n" % doctype
funcs = sorted(types[doctype], key=lambda _: _.__name__)
for f in funcs:
body += "## %s\n\n" % f.__name__
body += "### Args:\n"
if f.arglist[0][0]:
body += "**Arguments:**\n\n"
for key, value in f.arglist:
if key:
body += "**%s**: %s\n\n" % (key, value)
body += " * __%s__: %s\n\n" % (key, value)
else:
body += "__No arguments__"
body += "_requires no arguments_"
body += "\n\n" + pydoc.getdoc(f) + "\n\n"
body += "\n\n--------\n\n"
body += "\n<br>\n"
with open("documentation/docs/api_overview.md", "w") as output:
output.write(body)

34
server.py
View File

@ -176,18 +176,22 @@ def no_anon_hook(user, message=None, user_error=True):
class API(object):
"""
This object contains all the API endpoints for bbj.
The html serving part of the server is not written
yet, so this is currently the only module being
served.
This object contains all the API endpoints for bbj. The html serving
part of the server is not written yet, so this is currently the only
module being served.
The docstrings below are specifically formatted for the mkdocs static
site generator. The ugly `doctype` and `arglist` attributes assigned
after each method definition are for use in the `mkendpoints.py` script.
"""
@api_method
def user_register(self, args, database, user, **kwargs):
"""
Register a new user into the system and return the new object.
Requires the string arguments `user_name` and `auth_hash`.
Do not send User/Auth headers with this method.
Register a new user into the system and return the new user object
on success. The returned object includes the same `user_name` and
`auth_hash` that you supply, in addition to all the default user
parameters. Returns code 4 errors for any failures.
"""
validate(args, ["user_name", "auth_hash"])
return db.user_register(
@ -201,19 +205,23 @@ class API(object):
@api_method
def user_update(self, args, database, user, **kwargs):
"""
Receives new parameters and assigns them to the user_object
in the database. The following new parameters can be supplied:
`user_name`, `auth_hash`, `quip`, `bio`, and `color`. Any number
of them may be supplied.
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.
The newly updated user object is returned on success.
Take care to keep your client's User/Auth header pair up to date
after using this method.
The newly updated user object is returned on success,
including the `auth_hash`.
"""
no_anon_hook(user, "Anons cannot modify their account.")
validate(args, []) # just make sure its not empty
return db.user_update(database, user, args)
user_update.doctype = "Users"
user_update.arglist = (
("Any of the following may be submitted:", ""),
("Any of the following may be submitted", ""),
("user_name", "string: a desired display name"),
("auth_hash", "string: sha256 hash for a new password"),
("quip", "string: a short string that can be used as a signature"),