From f4aec05c4885f1c426ca8a1a2ea65b2571aa506c Mon Sep 17 00:00:00 2001 From: Blake DeMarcy Date: Thu, 4 May 2017 18:05:24 -0500 Subject: [PATCH] update some more docstrings --- docs/docs/api_overview.md | 56 +++++++++++++------------ docs/site/api_overview/index.html | 67 +++++++++++++++++------------- docs/site/index.html | 2 +- docs/site/mkdocs/search_index.json | 16 +++---- docs/site/sitemap.xml | 8 ++-- server.py | 56 +++++++++++++------------ 6 files changed, 108 insertions(+), 97 deletions(-) diff --git a/docs/docs/api_overview.md b/docs/docs/api_overview.md index 0432cf5..6ca1261 100644 --- a/docs/docs/api_overview.md +++ b/docs/docs/api_overview.md @@ -100,8 +100,8 @@ See also [the Authorization page](authorization.md). -Takes the arguments `target_user` and `target_hash`, and -returns boolean true or false whether the hash is valid. +Returns boolean `true` or `false` of whether the hash given +is correct for the given user.
@@ -189,35 +189,36 @@ on success. Returns a descriptive code 4 otherwise. * __time__: int/float: epoch/unix time of the earliest point of interest + * __OPTIONAL: format__: string: the specifier for the desired formatting engine -Returns a special object representing all activity on the board since -the argument `time`, a unix/epoch timestamp. +Returns a special object representing all activity on the board since `time`. + +```javascript { "threads": { "thread_id": { - ...thread object + // ...thread object }, - ...more thread_id/object pairs + // ...more thread_id/object pairs }, - "messages": [...standard message object array sorted by date] + "messages": [ + ...standard message object array sorted by date + ] } +``` -The message objects in "messages" are the same objects returned +The message objects in `messages` 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 "threads" object +you can access metadata for these threads by the `threads` object which is also provided. -The "messages" array is already sorted by submission time, newest +The `messages` array is already sorted by submission time, newest first. The order in the threads object is undefined and you should instead use their `last_mod` attribute if you intend to list them out visually. -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. -
## set_post_raw @@ -291,16 +292,15 @@ value, the OP message will never recieve special formatting. **Arguments:** - * __OPTIONAL: include_op__: boolean: Include a `messages` object with the original post + * __OPTIONAL: include_op__: boolean: Include a `messages` object containing the original post -Return an array with all the threads, ordered by most recent activity. -Requires no arguments. - -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). +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 `include_op`, these threads have no `messages` parameter. +If you do, the `messages` parameter is an array with a single message object +for the original post.
@@ -404,7 +404,10 @@ Requires the arguments `body` and `format`. Applies _requires no arguments_ Returns an array with all registered user_ids, with the usermap -object populated by their full objects. +object populated by their full objects. This method is _NEVER_ +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.
@@ -416,7 +419,7 @@ object populated by their full objects. _requires no arguments_ Requires no arguments. Returns your internal user object, -including your authorization hash. +including your `auth_hash`.
@@ -441,8 +444,7 @@ of whether that user is an admin. -Retreive an external user object for the given `target_user`. -Can be a user_id or user_name. +Returns a user object for the given target.
@@ -454,8 +456,8 @@ Can be a user_id or user_name. -Takes the argument `target_user` and returns true or false -whether they are in the system or not. +Returns boolean `true` or `false` of whether the given target is +registered on the server.
diff --git a/docs/site/api_overview/index.html b/docs/site/api_overview/index.html index 3e42628..f638e2f 100644 --- a/docs/site/api_overview/index.html +++ b/docs/site/api_overview/index.html @@ -203,8 +203,8 @@ choice. See the full error page for details.

target_hash: string: sha256 hash for the password to check

-

Takes the arguments target_user and target_hash, and -returns boolean true or false whether the hash is valid.

+

Returns boolean true or false of whether the hash given +is correct for the given user.




Threads & Messages

@@ -277,30 +277,35 @@ on success. Returns a descriptive code 4 otherwise.

message_feed

Arguments:

-

Returns a special object representing all activity on the board since -the argument time, a unix/epoch timestamp.

-

{ - "threads": { - "thread_id": { - ...thread object +

Returns a special object representing all activity on the board since time.

+
{
+    "threads": {
+        "thread_id": {
+            // ...thread object
         },
-        ...more thread_id/object pairs
+        // ...more thread_id/object pairs
     },
-    "messages": [...standard message object array sorted by date]
-}

-
The message objects in "messages" are the same objects returned
+    "messages": [
+        ...standard message object array sorted by date
+    ]
+}
+
+ +

The message objects in messages 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 "threads" object +you can access metadata for these threads by the threads object which is also provided.

-

The "messages" array is already sorted by submission time, newest +

The messages array is already sorted by submission time, newest first. The order in the threads object is undefined and you should instead use their last_mod attribute if you intend to list them out visually.

-

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.


set_post_raw

Arguments:

@@ -364,13 +369,13 @@ value, the OP message will never recieve special formatting.

thread_index

Arguments:

-

Return an array with all the threads, ordered by most recent activity. -Requires no arguments.

-

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).

+

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 include_op, these threads have no messages parameter. +If you do, the messages parameter is an array with a single message object +for the original post.


thread_load

Arguments:

@@ -459,7 +464,10 @@ provided value is safe to use.

user_map

requires no arguments

Returns an array with all registered user_ids, with the usermap -object populated by their full objects.

+object populated by their full objects. This method is NEVER +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.




Users

@@ -467,7 +475,7 @@ object populated by their full objects.

get_me

requires no arguments

Requires no arguments. Returns your internal user object, -including your authorization hash.

+including your auth_hash.


is_admin

Arguments:

@@ -482,16 +490,15 @@ of whether that user is an admin.

-

Retreive an external user object for the given target_user. -Can be a user_id or user_name.

+

Returns a user object for the given target.


user_is_registered

Arguments:

-

Takes the argument target_user and returns true or false -whether they are in the system or not.

+

Returns boolean true or false of whether the given target is +registered on the server.


user_register

Arguments:

diff --git a/docs/site/index.html b/docs/site/index.html index 5d92689..7930096 100644 --- a/docs/site/index.html +++ b/docs/site/index.html @@ -149,5 +149,5 @@ It is fully documented on this site.

diff --git a/docs/site/mkdocs/search_index.json b/docs/site/mkdocs/search_index.json index 3c1e2a2..c100c4e 100644 --- a/docs/site/mkdocs/search_index.json +++ b/docs/site/mkdocs/search_index.json @@ -22,7 +22,7 @@ }, { "location": "/api_overview/", - "text": "How to BBJ?\n\n\nInput\n\n\nBBJ is interacted with entirely through POST requests, whose bodies are\njson objects.\n\n\nThe endpoints, all listed below, can be contacted at the path /api/ relative\nto the root of where BBJ is hosted. If bbj is hosted on a server on port 80\nat the root:\n\n\nhttp://server.com/api/endpoint_here\n\n\nThe body of your request contains all of it's argument fields, instead of\nusing URL parameters. As a demonstration, to call \nthread_create\n,\nit requires two arguments: \ntitle\n, and \nbody\n. We put those argument\nnames at the root of the json object, and their values are the info\npassed into the API for that spot. Your input will look like this:\n\n\n{\n \"title\": \"Hello world!!\",\n \"body\": \"Hi! I am exploring this cool board thing!!\"\n}\n\n\n\n\nAnd you will POST this body to \nhttp://server.com:PORT/api/thread_create\n.\n\n\nA few endpoints do not require any arguments. These can still be POSTed to,\nbut the body may be completely empty or an empty json object. You can even\nGET these if you so choose.\n\n\nFor all endpoints, argument keys that are not consumed by the endpoint are\nignored. Posting an object with a key/value pair of \n\"sandwich\": True\n will\nnot clog up any pipes :) In the same vein, endpoints who dont take arguments\ndon't care if you supply them anyway.\n\n\nOutput\n\n\nBBJ returns data in a consistently formatted json object. The base object\nhas three keys: \ndata\n, \nusermap\n, and \nerror\n. Visualizied:\n\n\n{\n \"error\": false, // boolean false or error object\n \"data\": null, // null or the requested data from endpoint.\n \"usermap\": {} // potentially empty object, maps user_ids to user objects\n}\n\n// If \"error\" is true, it looks like this:\n\n{\n \"error\": {\n \"code\": // an integer from 0 to 5,\n \"description\": // a string describing the error in detail.\n }\n \"data\": null // ALWAYS null if error is not false\n \"usermap\": {} // ALWAYS empty if error is not false\n}\n\n\n\n\ndata\n\n\ndata\n is what the endpoint actually returns. The type of contents vary\nby endpoint and are documented below. If an endpoint says it returns a\nboolean, it will look like \n\"data\": True\n. If it says it returns an array,\nit will look like \n\"data\": [\"stuff\", \"goes\", \"here\"]\n\n\nusermap\n\n\nThe usermap is a json object mapping user_ids within \ndata\n to full user\nobjects. BBJ handles users entirely by an ID system, meaning any references\nto them inside of response data will not include vital information like their\nusername, or their profile information. Instead, we fetch those values from\nthis usermap object. All of it's root keys are user_id's and their values\nare user objects. It should be noted that the anonymous user has it's own\nID and profile object as well.\n\n\nerror\n\n\nerror\n is typically \nfalse\n. If it is \nnot\n false, then the request failed\nand the json object that \nerror\n contains should be inspected. (see the above\nvisualation) Errors follow a strict code system, making it easy for your client\nto map these responses to native exception types or signals in your language of\nchoice. See \nthe full error page\n for details.\n\n\n\n\nAuthorization\n\n\n\n\nSee also \nthe Authorization page\n.\n\n\ncheck_auth\n\n\nArguments:\n\n\n\n\n\n\ntarget_user\n: string: either a user_name or a user_id\n\n\n\n\n\n\ntarget_hash\n: string: sha256 hash for the password to check\n\n\n\n\n\n\nTakes the arguments \ntarget_user\n and \ntarget_hash\n, and\nreturns boolean true or false whether the hash is valid.\n\n\n\n\n\n\nThreads & Messages\n\n\n\n\ndelete_post\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread this message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the id of the target message.\n\n\n\n\n\n\nRequires the arguments \nthread_id\n and \npost_id\n.\n\n\nDelete a message from a thread. The same rules apply\nhere as \nedit_post\n and \nedit_query\n: the logged in user\nmust either be the one who posted the message within 24hrs,\nor have admin rights. The same error descriptions and code\nare returned on falilure. Boolean true is returned on\nsuccess.\n\n\nIf the post_id is 0, the whole thread is deleted.\n\n\n\n\nedit_post\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the thread the message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the target post_id to edit.\n\n\n\n\n\n\nbody\n: string: the new message body.\n\n\n\n\n\n\nOPTIONAL: send_raw\n: boolean: set the formatting mode for the target message.\n\n\n\n\n\n\nReplace a post with a new body. Requires the arguments\n\nthread_id\n, \npost_id\n, and \nbody\n. This method verifies\nthat the user can edit a post before commiting the change,\notherwise an error object is returned whose description\nshould be shown to the user.\n\n\nTo perform sanity checks and retrieve the unformatted body\nof a post without actually attempting to replace it, use\n\nedit_query\n first.\n\n\nOptionally you may also include the argument \nsend_raw\n to\nset the message's formatting flag. However, if this is the\nonly change you would like to make, you should use the\nendpoint \nset_post_raw\n instead.\n\n\nReturns the new message object.\n\n\n\n\nedit_query\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread the message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the id of the target message.\n\n\n\n\n\n\nQueries the database to ensure the user can edit a given\nmessage. Requires the arguments \nthread_id\n and \npost_id\n\n(does not require a new body)\n\n\nReturns the original message object without any formatting\non success. Returns a descriptive code 4 otherwise.\n\n\n\n\nmessage_feed\n\n\nArguments:\n\n\n\n\ntime\n: int/float: epoch/unix time of the earliest point of interest\n\n\n\n\nReturns a special object representing all activity on the board since\nthe argument \ntime\n, a unix/epoch timestamp.\n\n\n{\n \"threads\": {\n \"thread_id\": {\n ...thread object\n },\n ...more thread_id/object pairs\n },\n \"messages\": [...standard message object array sorted by date]\n}\n\n\nThe message objects in \"messages\" are the same objects returned\nin threads normally. They each have a thread_id parameter, and\nyou can access metadata for these threads by the \"threads\" object\nwhich is also provided.\n\n\nThe \"messages\" array is already sorted by submission time, newest\nfirst. The order in the threads object is undefined and you should\ninstead use their \nlast_mod\n attribute if you intend to list them\nout visually.\n\n\nYou may optionally provide a \nformat\n argument: this is treated\nthe same way as the \nthread_load\n endpoint and you should refer\nto its documentation for more info.\n\n\n\n\nset_post_raw\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread the message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the id of the target message.\n\n\n\n\n\n\nvalue\n: boolean: the new \nsend_raw\n value to apply to the message.\n\n\n\n\n\n\nRequires the boolean argument of \nvalue\n, string argument\n\nthread_id\n, and integer argument \npost_id\n. \nvalue\n, when false,\nmeans that the message will be passed through message formatters\nbefore being sent to clients. When \nvalue\n is true, this means\nit will never go through formatters, all of its whitespace is\nsent to clients verbatim and expressions are not processed.\n\n\nThe same rules for editing messages (see \nedit_query\n) apply here\nand the same error objects are returned for violations.\n\n\nYou may optionally set this value as well when using \nedit_post\n,\nbut if this is the only change you want to make to the message,\nusing this endpoint instead is preferable.\n\n\n\n\nset_thread_pin\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread to modify.\n\n\n\n\n\n\nvalue\n: boolean: \ntrue\n to pin thread, \nfalse\n otherwise.\n\n\n\n\n\n\nRequires the arguments \nthread_id\n and \nvalue\n. \nvalue\n\nmust be a boolean of what the pinned status should be.\nThis method requires that the caller is logged in and\nhas admin status on their account.\n\n\nReturns the same boolean you supply as \nvalue\n\n\n\n\nthread_create\n\n\nArguments:\n\n\n\n\n\n\nbody\n: string: The body of the first message\n\n\n\n\n\n\ntitle\n: string: The title name for this thread\n\n\n\n\n\n\nOPTIONAL: send_raw\n: boolean: formatting mode for the first message.\n\n\n\n\n\n\nCreates a new thread and returns it. Requires the non-empty\nstring arguments \nbody\n and \ntitle\n.\n\n\nIf the argument \nsend_raw\n is specified and has a non-nil\nvalue, the OP message will never recieve special formatting.\n\n\n\n\nthread_index\n\n\nArguments:\n\n\n\n\nOPTIONAL: include_op\n: boolean: Include a \nmessages\n object with the original post\n\n\n\n\nReturn an array with all the threads, ordered by most recent activity.\nRequires no arguments.\n\n\nOptionally, you may supply the argument \ninclude_op\n, which, when\nnon-nil, will include a \"messages\" key with the object, whose sole\ncontent is the original message (post_id 0).\n\n\n\n\nthread_load\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the thread to load.\n\n\n\n\n\n\nOPTIONAL: op_only\n: boolean: include only the original message in \nmessages\n\n\n\n\n\n\nOPTIONAL: format\n: string: the formatting type of the returned messages.\n\n\n\n\n\n\nReturns the thread object with all of its messages loaded.\nRequires the argument \nthread_id\n. \nformat\n may also be\nspecified as a formatter to run the messages through.\nCurrently only \"sequential\" is supported.\n\n\nYou may also supply the parameter \nop_only\n. When it's value\nis non-nil, the messages array will only include post_id 0 (the first)\n\n\n\n\nthread_reply\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id for the thread this message should post to.\n\n\n\n\n\n\nbody\n: string: the message's body of text.\n\n\n\n\n\n\nOPTIONAL: send_raw\n: boolean: formatting mode for the posted message.\n\n\n\n\n\n\nCreates a new reply for the given thread and returns it.\nRequires the string arguments \nthread_id\n and \nbody\n\n\nIf the argument \nsend_raw\n is specified and has a non-nil\nvalue, the message will never recieve special formatting.\n\n\n\n\n\n\nTools\n\n\n\n\ndb_validate\n\n\nArguments:\n\n\n\n\n\n\nkey\n: string: the identifier for the ruleset to check.\n\n\n\n\n\n\nvalue\n: VARIES: the object for which \nkey\n will check for.\n\n\n\n\n\n\nOPTIONAL: error\n: boolean: when \ntrue\n, will return an API error response instead of a special object.\n\n\n\n\n\n\nRequires the arguments \nkey\n and \nvalue\n. Returns an object\nwith information about the database sanity criteria for\nkey. This can be used to validate user input in the client\nbefore trying to send it to the server.\n\n\nIf the argument \nerror\n is supplied with a non-nil value,\nthe server will return a standard error object on failure\ninstead of the special object described below.\n\n\nThe returned object has two keys:\n\n\n{\n \"bool\": true/false,\n \"description\": null/\"why this value is bad\"\n}\n\n\nIf bool == false, description is a string describing the\nproblem. If bool == true, description is null and the\nprovided value is safe to use.\n\n\n\n\nformat_message\n\n\nArguments:\n\n\n\n\n\n\nbody\n: string: the message body to apply formatting to.\n\n\n\n\n\n\nformat\n: string: the specifier for the desired formatting engine\n\n\n\n\n\n\nRequires the arguments \nbody\n and \nformat\n. Applies\n\nformat\n to \nbody\n and returns the new object. See\n\nthread_load\n for supported specifications for \nformat\n.\n\n\n\n\nuser_map\n\n\nrequires no arguments\n\n\nReturns an array with all registered user_ids, with the usermap\nobject populated by their full objects.\n\n\n\n\n\n\nUsers\n\n\n\n\nget_me\n\n\nrequires no arguments\n\n\nRequires no arguments. Returns your internal user object,\nincluding your authorization hash.\n\n\n\n\nis_admin\n\n\nArguments:\n\n\n\n\ntarget_user\n: string: user_id or user_name to check against.\n\n\n\n\nRequires the argument \ntarget_user\n. Returns a boolean\nof whether that user is an admin.\n\n\n\n\nuser_get\n\n\nArguments:\n\n\n\n\ntarget_user\n: string: either a user_name or a user_id\n\n\n\n\nRetreive an external user object for the given \ntarget_user\n.\nCan be a user_id or user_name.\n\n\n\n\nuser_is_registered\n\n\nArguments:\n\n\n\n\ntarget_user\n: string: either a user_name or a user_id\n\n\n\n\nTakes the argument \ntarget_user\n and returns true or false\nwhether they are in the system or not.\n\n\n\n\nuser_register\n\n\nArguments:\n\n\n\n\n\n\nuser_name\n: string: the desired display name\n\n\n\n\n\n\nauth_hash\n: string: a sha256 hash of a password\n\n\n\n\n\n\nRegister a new user into the system and return the new user object\non success. The returned object includes the same \nuser_name\n and\n\nauth_hash\n that you supply, in addition to all the default user\nparameters. Returns code 4 errors for any failures.\n\n\n\n\nuser_update\n\n\nArguments:\n\n\n\n\n\n\nAny of the following may be submitted\n: \n\n\n\n\n\n\nuser_name\n: string: a desired display name\n\n\n\n\n\n\nauth_hash\n: string: sha256 hash for a new password\n\n\n\n\n\n\nquip\n: string: a short string that can be used as a signature\n\n\n\n\n\n\nbio\n: string: a user biography for their profile\n\n\n\n\n\n\ncolor\n: integer: 0-6, a display color for the user\n\n\n\n\n\n\nReceives new parameters and assigns them to the user object.\nThis method requires that you send a valid User/Auth header\npair with your request, and the changes are made to that\naccount.\n\n\nTake care to keep your client's User/Auth header pair up to date\nafter using this method.\n\n\nThe newly updated user object is returned on success,\nincluding the \nauth_hash\n.", + "text": "How to BBJ?\n\n\nInput\n\n\nBBJ is interacted with entirely through POST requests, whose bodies are\njson objects.\n\n\nThe endpoints, all listed below, can be contacted at the path /api/ relative\nto the root of where BBJ is hosted. If bbj is hosted on a server on port 80\nat the root:\n\n\nhttp://server.com/api/endpoint_here\n\n\nThe body of your request contains all of it's argument fields, instead of\nusing URL parameters. As a demonstration, to call \nthread_create\n,\nit requires two arguments: \ntitle\n, and \nbody\n. We put those argument\nnames at the root of the json object, and their values are the info\npassed into the API for that spot. Your input will look like this:\n\n\n{\n \"title\": \"Hello world!!\",\n \"body\": \"Hi! I am exploring this cool board thing!!\"\n}\n\n\n\n\nAnd you will POST this body to \nhttp://server.com:PORT/api/thread_create\n.\n\n\nA few endpoints do not require any arguments. These can still be POSTed to,\nbut the body may be completely empty or an empty json object. You can even\nGET these if you so choose.\n\n\nFor all endpoints, argument keys that are not consumed by the endpoint are\nignored. Posting an object with a key/value pair of \n\"sandwich\": True\n will\nnot clog up any pipes :) In the same vein, endpoints who dont take arguments\ndon't care if you supply them anyway.\n\n\nOutput\n\n\nBBJ returns data in a consistently formatted json object. The base object\nhas three keys: \ndata\n, \nusermap\n, and \nerror\n. Visualizied:\n\n\n{\n \"error\": false, // boolean false or error object\n \"data\": null, // null or the requested data from endpoint.\n \"usermap\": {} // potentially empty object, maps user_ids to user objects\n}\n\n// If \"error\" is true, it looks like this:\n\n{\n \"error\": {\n \"code\": // an integer from 0 to 5,\n \"description\": // a string describing the error in detail.\n }\n \"data\": null // ALWAYS null if error is not false\n \"usermap\": {} // ALWAYS empty if error is not false\n}\n\n\n\n\ndata\n\n\ndata\n is what the endpoint actually returns. The type of contents vary\nby endpoint and are documented below. If an endpoint says it returns a\nboolean, it will look like \n\"data\": True\n. If it says it returns an array,\nit will look like \n\"data\": [\"stuff\", \"goes\", \"here\"]\n\n\nusermap\n\n\nThe usermap is a json object mapping user_ids within \ndata\n to full user\nobjects. BBJ handles users entirely by an ID system, meaning any references\nto them inside of response data will not include vital information like their\nusername, or their profile information. Instead, we fetch those values from\nthis usermap object. All of it's root keys are user_id's and their values\nare user objects. It should be noted that the anonymous user has it's own\nID and profile object as well.\n\n\nerror\n\n\nerror\n is typically \nfalse\n. If it is \nnot\n false, then the request failed\nand the json object that \nerror\n contains should be inspected. (see the above\nvisualation) Errors follow a strict code system, making it easy for your client\nto map these responses to native exception types or signals in your language of\nchoice. See \nthe full error page\n for details.\n\n\n\n\nAuthorization\n\n\n\n\nSee also \nthe Authorization page\n.\n\n\ncheck_auth\n\n\nArguments:\n\n\n\n\n\n\ntarget_user\n: string: either a user_name or a user_id\n\n\n\n\n\n\ntarget_hash\n: string: sha256 hash for the password to check\n\n\n\n\n\n\nReturns boolean \ntrue\n or \nfalse\n of whether the hash given\nis correct for the given user.\n\n\n\n\n\n\nThreads & Messages\n\n\n\n\ndelete_post\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread this message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the id of the target message.\n\n\n\n\n\n\nRequires the arguments \nthread_id\n and \npost_id\n.\n\n\nDelete a message from a thread. The same rules apply\nhere as \nedit_post\n and \nedit_query\n: the logged in user\nmust either be the one who posted the message within 24hrs,\nor have admin rights. The same error descriptions and code\nare returned on falilure. Boolean true is returned on\nsuccess.\n\n\nIf the post_id is 0, the whole thread is deleted.\n\n\n\n\nedit_post\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the thread the message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the target post_id to edit.\n\n\n\n\n\n\nbody\n: string: the new message body.\n\n\n\n\n\n\nOPTIONAL: send_raw\n: boolean: set the formatting mode for the target message.\n\n\n\n\n\n\nReplace a post with a new body. Requires the arguments\n\nthread_id\n, \npost_id\n, and \nbody\n. This method verifies\nthat the user can edit a post before commiting the change,\notherwise an error object is returned whose description\nshould be shown to the user.\n\n\nTo perform sanity checks and retrieve the unformatted body\nof a post without actually attempting to replace it, use\n\nedit_query\n first.\n\n\nOptionally you may also include the argument \nsend_raw\n to\nset the message's formatting flag. However, if this is the\nonly change you would like to make, you should use the\nendpoint \nset_post_raw\n instead.\n\n\nReturns the new message object.\n\n\n\n\nedit_query\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread the message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the id of the target message.\n\n\n\n\n\n\nQueries the database to ensure the user can edit a given\nmessage. Requires the arguments \nthread_id\n and \npost_id\n\n(does not require a new body)\n\n\nReturns the original message object without any formatting\non success. Returns a descriptive code 4 otherwise.\n\n\n\n\nmessage_feed\n\n\nArguments:\n\n\n\n\n\n\ntime\n: int/float: epoch/unix time of the earliest point of interest\n\n\n\n\n\n\nOPTIONAL: format\n: string: the specifier for the desired formatting engine\n\n\n\n\n\n\nReturns a special object representing all activity on the board since \ntime\n.\n\n\n{\n \"threads\": {\n \"thread_id\": {\n // ...thread object\n },\n // ...more thread_id/object pairs\n },\n \"messages\": [\n ...standard message object array sorted by date\n ]\n}\n\n\n\n\nThe message objects in \nmessages\n are the same objects returned\nin threads normally. They each have a thread_id parameter, and\nyou can access metadata for these threads by the \nthreads\n object\nwhich is also provided.\n\n\nThe \nmessages\n array is already sorted by submission time, newest\nfirst. The order in the threads object is undefined and you should\ninstead use their \nlast_mod\n attribute if you intend to list them\nout visually.\n\n\n\n\nset_post_raw\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread the message was posted in.\n\n\n\n\n\n\npost_id\n: integer: the id of the target message.\n\n\n\n\n\n\nvalue\n: boolean: the new \nsend_raw\n value to apply to the message.\n\n\n\n\n\n\nRequires the boolean argument of \nvalue\n, string argument\n\nthread_id\n, and integer argument \npost_id\n. \nvalue\n, when false,\nmeans that the message will be passed through message formatters\nbefore being sent to clients. When \nvalue\n is true, this means\nit will never go through formatters, all of its whitespace is\nsent to clients verbatim and expressions are not processed.\n\n\nThe same rules for editing messages (see \nedit_query\n) apply here\nand the same error objects are returned for violations.\n\n\nYou may optionally set this value as well when using \nedit_post\n,\nbut if this is the only change you want to make to the message,\nusing this endpoint instead is preferable.\n\n\n\n\nset_thread_pin\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id of the thread to modify.\n\n\n\n\n\n\nvalue\n: boolean: \ntrue\n to pin thread, \nfalse\n otherwise.\n\n\n\n\n\n\nRequires the arguments \nthread_id\n and \nvalue\n. \nvalue\n\nmust be a boolean of what the pinned status should be.\nThis method requires that the caller is logged in and\nhas admin status on their account.\n\n\nReturns the same boolean you supply as \nvalue\n\n\n\n\nthread_create\n\n\nArguments:\n\n\n\n\n\n\nbody\n: string: The body of the first message\n\n\n\n\n\n\ntitle\n: string: The title name for this thread\n\n\n\n\n\n\nOPTIONAL: send_raw\n: boolean: formatting mode for the first message.\n\n\n\n\n\n\nCreates a new thread and returns it. Requires the non-empty\nstring arguments \nbody\n and \ntitle\n.\n\n\nIf the argument \nsend_raw\n is specified and has a non-nil\nvalue, the OP message will never recieve special formatting.\n\n\n\n\nthread_index\n\n\nArguments:\n\n\n\n\nOPTIONAL: include_op\n: boolean: Include a \nmessages\n object containing the original post\n\n\n\n\nReturn an array with all the server's threads. They are already sorted for\nyou; most recently modified threads are at the beginning of the array.\nUnless you supply \ninclude_op\n, these threads have no \nmessages\n parameter.\nIf you do, the \nmessages\n parameter is an array with a single message object\nfor the original post.\n\n\n\n\nthread_load\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the thread to load.\n\n\n\n\n\n\nOPTIONAL: op_only\n: boolean: include only the original message in \nmessages\n\n\n\n\n\n\nOPTIONAL: format\n: string: the formatting type of the returned messages.\n\n\n\n\n\n\nReturns the thread object with all of its messages loaded.\nRequires the argument \nthread_id\n. \nformat\n may also be\nspecified as a formatter to run the messages through.\nCurrently only \"sequential\" is supported.\n\n\nYou may also supply the parameter \nop_only\n. When it's value\nis non-nil, the messages array will only include post_id 0 (the first)\n\n\n\n\nthread_reply\n\n\nArguments:\n\n\n\n\n\n\nthread_id\n: string: the id for the thread this message should post to.\n\n\n\n\n\n\nbody\n: string: the message's body of text.\n\n\n\n\n\n\nOPTIONAL: send_raw\n: boolean: formatting mode for the posted message.\n\n\n\n\n\n\nCreates a new reply for the given thread and returns it.\nRequires the string arguments \nthread_id\n and \nbody\n\n\nIf the argument \nsend_raw\n is specified and has a non-nil\nvalue, the message will never recieve special formatting.\n\n\n\n\n\n\nTools\n\n\n\n\ndb_validate\n\n\nArguments:\n\n\n\n\n\n\nkey\n: string: the identifier for the ruleset to check.\n\n\n\n\n\n\nvalue\n: VARIES: the object for which \nkey\n will check for.\n\n\n\n\n\n\nOPTIONAL: error\n: boolean: when \ntrue\n, will return an API error response instead of a special object.\n\n\n\n\n\n\nRequires the arguments \nkey\n and \nvalue\n. Returns an object\nwith information about the database sanity criteria for\nkey. This can be used to validate user input in the client\nbefore trying to send it to the server.\n\n\nIf the argument \nerror\n is supplied with a non-nil value,\nthe server will return a standard error object on failure\ninstead of the special object described below.\n\n\nThe returned object has two keys:\n\n\n{\n \"bool\": true/false,\n \"description\": null/\"why this value is bad\"\n}\n\n\nIf bool == false, description is a string describing the\nproblem. If bool == true, description is null and the\nprovided value is safe to use.\n\n\n\n\nformat_message\n\n\nArguments:\n\n\n\n\n\n\nbody\n: string: the message body to apply formatting to.\n\n\n\n\n\n\nformat\n: string: the specifier for the desired formatting engine\n\n\n\n\n\n\nRequires the arguments \nbody\n and \nformat\n. Applies\n\nformat\n to \nbody\n and returns the new object. See\n\nthread_load\n for supported specifications for \nformat\n.\n\n\n\n\nuser_map\n\n\nrequires no arguments\n\n\nReturns an array with all registered user_ids, with the usermap\nobject populated by their full objects. This method is \nNEVER\n\nneccesary when using other endpoints, as the usermap returned\non those requests already contains all the information you will\nneed. This endpoint is useful for statistic purposes only.\n\n\n\n\n\n\nUsers\n\n\n\n\nget_me\n\n\nrequires no arguments\n\n\nRequires no arguments. Returns your internal user object,\nincluding your \nauth_hash\n.\n\n\n\n\nis_admin\n\n\nArguments:\n\n\n\n\ntarget_user\n: string: user_id or user_name to check against.\n\n\n\n\nRequires the argument \ntarget_user\n. Returns a boolean\nof whether that user is an admin.\n\n\n\n\nuser_get\n\n\nArguments:\n\n\n\n\ntarget_user\n: string: either a user_name or a user_id\n\n\n\n\nReturns a user object for the given target.\n\n\n\n\nuser_is_registered\n\n\nArguments:\n\n\n\n\ntarget_user\n: string: either a user_name or a user_id\n\n\n\n\nReturns boolean \ntrue\n or \nfalse\n of whether the given target is\nregistered on the server.\n\n\n\n\nuser_register\n\n\nArguments:\n\n\n\n\n\n\nuser_name\n: string: the desired display name\n\n\n\n\n\n\nauth_hash\n: string: a sha256 hash of a password\n\n\n\n\n\n\nRegister a new user into the system and return the new user object\non success. The returned object includes the same \nuser_name\n and\n\nauth_hash\n that you supply, in addition to all the default user\nparameters. Returns code 4 errors for any failures.\n\n\n\n\nuser_update\n\n\nArguments:\n\n\n\n\n\n\nAny of the following may be submitted\n: \n\n\n\n\n\n\nuser_name\n: string: a desired display name\n\n\n\n\n\n\nauth_hash\n: string: sha256 hash for a new password\n\n\n\n\n\n\nquip\n: string: a short string that can be used as a signature\n\n\n\n\n\n\nbio\n: string: a user biography for their profile\n\n\n\n\n\n\ncolor\n: integer: 0-6, a display color for the user\n\n\n\n\n\n\nReceives new parameters and assigns them to the user object.\nThis method requires that you send a valid User/Auth header\npair with your request, and the changes are made to that\naccount.\n\n\nTake care to keep your client's User/Auth header pair up to date\nafter using this method.\n\n\nThe newly updated user object is returned on success,\nincluding the \nauth_hash\n.", "title": "Overview & Endpoints" }, { @@ -62,7 +62,7 @@ }, { "location": "/api_overview/#check_auth", - "text": "Arguments: target_user : string: either a user_name or a user_id target_hash : string: sha256 hash for the password to check Takes the arguments target_user and target_hash , and\nreturns boolean true or false whether the hash is valid.", + "text": "Arguments: target_user : string: either a user_name or a user_id target_hash : string: sha256 hash for the password to check Returns boolean true or false of whether the hash given\nis correct for the given user.", "title": "check_auth" }, { @@ -87,7 +87,7 @@ }, { "location": "/api_overview/#message_feed", - "text": "Arguments: time : int/float: epoch/unix time of the earliest point of interest Returns a special object representing all activity on the board since\nthe argument time , a unix/epoch timestamp. {\n \"threads\": {\n \"thread_id\": {\n ...thread object\n },\n ...more thread_id/object pairs\n },\n \"messages\": [...standard message object array sorted by date]\n} The message objects in \"messages\" are the same objects returned\nin threads normally. They each have a thread_id parameter, and\nyou can access metadata for these threads by the \"threads\" object\nwhich is also provided. The \"messages\" array is already sorted by submission time, newest\nfirst. The order in the threads object is undefined and you should\ninstead use their last_mod attribute if you intend to list them\nout visually. You may optionally provide a format argument: this is treated\nthe same way as the thread_load endpoint and you should refer\nto its documentation for more info.", + "text": "Arguments: time : int/float: epoch/unix time of the earliest point of interest OPTIONAL: format : string: the specifier for the desired formatting engine Returns a special object representing all activity on the board since time . {\n \"threads\": {\n \"thread_id\": {\n // ...thread object\n },\n // ...more thread_id/object pairs\n },\n \"messages\": [\n ...standard message object array sorted by date\n ]\n} The message objects in messages are the same objects returned\nin threads normally. They each have a thread_id parameter, and\nyou can access metadata for these threads by the threads object\nwhich is also provided. The messages array is already sorted by submission time, newest\nfirst. The order in the threads object is undefined and you should\ninstead use their last_mod attribute if you intend to list them\nout visually.", "title": "message_feed" }, { @@ -107,7 +107,7 @@ }, { "location": "/api_overview/#thread_index", - "text": "Arguments: OPTIONAL: include_op : boolean: Include a messages object with the original post Return an array with all the threads, ordered by most recent activity.\nRequires no arguments. Optionally, you may supply the argument include_op , which, when\nnon-nil, will include a \"messages\" key with the object, whose sole\ncontent is the original message (post_id 0).", + "text": "Arguments: OPTIONAL: include_op : boolean: Include a messages object containing the original post Return an array with all the server's threads. They are already sorted for\nyou; most recently modified threads are at the beginning of the array.\nUnless you supply include_op , these threads have no messages parameter.\nIf you do, the messages parameter is an array with a single message object\nfor the original post.", "title": "thread_index" }, { @@ -137,7 +137,7 @@ }, { "location": "/api_overview/#user_map", - "text": "requires no arguments Returns an array with all registered user_ids, with the usermap\nobject populated by their full objects.", + "text": "requires no arguments Returns an array with all registered user_ids, with the usermap\nobject populated by their full objects. This method is NEVER \nneccesary when using other endpoints, as the usermap returned\non those requests already contains all the information you will\nneed. This endpoint is useful for statistic purposes only.", "title": "user_map" }, { @@ -147,7 +147,7 @@ }, { "location": "/api_overview/#get_me", - "text": "requires no arguments Requires no arguments. Returns your internal user object,\nincluding your authorization hash.", + "text": "requires no arguments Requires no arguments. Returns your internal user object,\nincluding your auth_hash .", "title": "get_me" }, { @@ -157,12 +157,12 @@ }, { "location": "/api_overview/#user_get", - "text": "Arguments: target_user : string: either a user_name or a user_id Retreive an external user object for the given target_user .\nCan be a user_id or user_name.", + "text": "Arguments: target_user : string: either a user_name or a user_id Returns a user object for the given target.", "title": "user_get" }, { "location": "/api_overview/#user_is_registered", - "text": "Arguments: target_user : string: either a user_name or a user_id Takes the argument target_user and returns true or false\nwhether they are in the system or not.", + "text": "Arguments: target_user : string: either a user_name or a user_id Returns boolean true or false of whether the given target is\nregistered on the server.", "title": "user_is_registered" }, { diff --git a/docs/site/sitemap.xml b/docs/site/sitemap.xml index fd79ccf..5b8dbee 100644 --- a/docs/site/sitemap.xml +++ b/docs/site/sitemap.xml @@ -4,7 +4,7 @@ / - 2017-05-03 + 2017-05-04 daily @@ -13,19 +13,19 @@ /api_overview/ - 2017-05-03 + 2017-05-04 daily /errors/ - 2017-05-03 + 2017-05-04 daily /validation/ - 2017-05-03 + 2017-05-04 daily diff --git a/server.py b/server.py index 6061566..456c560 100644 --- a/server.py +++ b/server.py @@ -233,7 +233,7 @@ class API(object): def get_me(self, args, database, user, **kwargs): """ Requires no arguments. Returns your internal user object, - including your authorization hash. + including your `auth_hash`. """ return user get_me.doctype = "Users" @@ -243,7 +243,10 @@ class API(object): def user_map(self, args, database, user, **kwargs): """ Returns an array with all registered user_ids, with the usermap - object populated by their full objects. + object populated by their full objects. This method is _NEVER_ + 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. """ users = { user[0] for user in database.execute("SELECT user_id FROM users") @@ -263,8 +266,7 @@ class API(object): @api_method def user_get(self, args, database, user, **kwargs): """ - Retreive an external user object for the given `target_user`. - Can be a user_id or user_name. + Returns a user object for the given target. """ validate(args, ["target_user"]) return db.user_resolve( @@ -277,8 +279,8 @@ class API(object): @api_method def user_is_registered(self, args, database, user, **kwargs): """ - Takes the argument `target_user` and returns true or false - whether they are in the system or not. + Returns boolean `true` or `false` of whether the given target is + registered on the server. """ validate(args, ["target_user"]) return bool(db.user_resolve(database, args["target_user"])) @@ -290,8 +292,8 @@ class API(object): @api_method def check_auth(self, args, database, user, **kwargs): """ - Takes the arguments `target_user` and `target_hash`, and - returns boolean true or false whether the hash is valid. + Returns boolean `true` or `false` of whether the hash given + is correct for the given user. """ validate(args, ["target_user", "target_hash"]) user = db.user_resolve( @@ -306,51 +308,50 @@ class API(object): @api_method def thread_index(self, args, database, user, **kwargs): """ - Return an array with all the threads, ordered by most recent activity. - Requires no arguments. - - 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). + 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 `include_op`, these threads have no `messages` parameter. + If you do, the `messages` parameter is an array with a single message object + for the original post. """ threads = db.thread_index(database, include_op=args.get("include_op")) cherrypy.thread_data.usermap = create_usermap(database, threads, True) return threads thread_index.doctype = "Threads & Messages" thread_index.arglist = ( - ("OPTIONAL: include_op", "boolean: Include a `messages` object with the original post"), + ("OPTIONAL: include_op", "boolean: Include a `messages` object containing the original post"), ) @api_method def message_feed(self, args, database, user, **kwargs): """ - Returns a special object representing all activity on the board since - the argument `time`, a unix/epoch timestamp. + Returns a special object representing all activity on the board since `time`. + ```javascript { "threads": { "thread_id": { - ...thread object + // ...thread object }, - ...more thread_id/object pairs + // ...more thread_id/object pairs }, - "messages": [...standard message object array sorted by date] + "messages": [ + ...standard message object array sorted by date + ] } + ``` - The message objects in "messages" are the same objects returned + The message objects in `messages` 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 "threads" object + you can access metadata for these threads by the `threads` object which is also provided. - The "messages" array is already sorted by submission time, newest + The `messages` array is already sorted by submission time, newest first. The order in the threads object is undefined and you should instead use their `last_mod` attribute if you intend to list them out visually. - - 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. """ + # XXX: Update with new formatting documentation for arg `format` validate(args, ["time"]) feed = db.message_feed(database, args["time"]) @@ -363,6 +364,7 @@ class API(object): message_feed.doctype = "Threads & Messages" message_feed.arglist = ( ("time", "int/float: epoch/unix time of the earliest point of interest"), + ("OPTIONAL: format", "string: the specifier for the desired formatting engine") ) @api_method