From b2df9b0332b4b2cf4f81b00189187c7f5fe8bfe1 Mon Sep 17 00:00:00 2001 From: Chip Black Date: Thu, 31 Jul 2014 01:00:39 -0500 Subject: [PATCH] Update docs for API changes --- www/css/doc.css | 16 +++++++ www/doc/index.html | 114 +++++++++++++++++++++++++++------------------ 2 files changed, 84 insertions(+), 46 deletions(-) diff --git a/www/css/doc.css b/www/css/doc.css index 1173b95..adfe20c 100644 --- a/www/css/doc.css +++ b/www/css/doc.css @@ -9,6 +9,11 @@ body { h1, h2, h3, h4, h5 { font-family: sans-serif; clear: both; + margin-bottom: 0.5em; +} + +h1 + p, h2 + p, h3 + p, h4 + p, h5 + p { + margin-top: 0.5em; } pre { @@ -68,6 +73,17 @@ pre { height: 16px; } +.feature { + font-family: sans-serif; + font-size: 12pt; + color: #707010; + font-weight: bold; +} + +h3 + .feature { + margin-top: -10px; +} + .magic { display: none; } diff --git a/www/doc/index.html b/www/doc/index.html index 61b8035..2040f16 100644 --- a/www/doc/index.html +++ b/www/doc/index.html @@ -30,6 +30,7 @@ C.
  • API
    • @@ -205,7 +205,7 @@ root of the wesite. response, like 404 Not Found if a record or user doesn't exist, or a 200 response with a 'JSON failure', which will look like this: -

    {"status": "failure"} +

    {"status": "failure"}

    Blërg doesn't currently explain why there is a failure, and I'm not sure it ever will. @@ -214,7 +214,7 @@ I'm not sure it ever will. /get, /tag, or /info), or a 'JSON success' response (for /create, /put, /login, or /logout), which looks like this: -

    {"status": "success"} +

    {"status": "success"}

    For the CGI backend, you may get a 500 error if something goes wrong. For the HTTP backend, you'll get nothing (since it will have crashed), @@ -229,6 +229,20 @@ because I use strncmp(3) to compare).

    Tags must be 64 characters or less, and can contain only the ASCII characters 0-9, A-Z, a-z, underscore (_), and hyphen (-). +

    Authorization

    + +

    As the result of a successful login, the server +will send back a cookie named auth. This cookie authorizes +restricted requests, and must be sent for any API endpoint marked authorization, or else you will get a 403 Forbidden +response. The cookie format looks like: + +auth=username/abcdef0123456789abcdef0123456789 + +That is a username, a forward slash, and 32 hexadecimal digits which denote the +"token" identifying the session. On logout, the server will invalidate the +token and expire the cookie. +

    /create - create a new user

    To create a user, POST to /create with username and @@ -244,24 +258,24 @@ success if the user is created. respond with JSON failure if the user does not exist or if the password is incorrect. On success, the server will respond with JSON success, and will set a cookie named 'auth' that must be sent by the client when -accessing restricted API functions (/put and /logout). +accessing restricted API functions (See Authorization above).

    /logout - log out

    +
    authorization
    -

    POST to /logout with with username, the user to log out, -along with the auth cookie in a Cookie header. The server will respond -with JSON failure if the user does not exist or if the auth cookie is -bad. The server will respond with JSON success after the user is -successfully logged out. +

    POST to /logout. The server will respond with JSON failure if the +user does not exist or if the request is unauthorized. The server will +respond with JSON success after the user is successfully logged out.

    /put - add a new record

    +
    authorization
    -

    POST to /put with username and data -parameters, and an auth cookie. The server will respond with JSON -failure if the auth cookie is bad, if the user doesn't exist, or if -data contains more than 65535 bytes after URL -decoding. The server will respond with JSON success after the record is -successfully added. +

    POST to /put with a data parameter. The server will +respond with JSON failure if the request is unauthorized, if the user +doesn't exist, or if data contains more than 65535 bytes +after URL decoding. The server will respond with JSON success +after the record is successfully added.

    /get/(user), /get/(user)/(start record)-(end record) - get records for a user

    @@ -332,45 +346,52 @@ will probably mutate to work like /get.

    /subscribe/(user) - Subscribe to a user's updates

    +
    authorization
    -

    POST to /subscribe/(user) with a username parameter and -an auth cookie, where (user) is the user whose updates you wish to -subscribe to. The server will respond with JSON failure if the auth -cookie is bad or if the user doesn't exist. The server will respond -with JSON success after the subscription is successfully registered. - -

    /unsubscribe/(user) - Unsubscribe from -a user's updates

    - -

    Identical to /subscribe, but removes the subscription. +

    POST to /subscribe/(user) with a subscribed parameter +that is either "true" or "false", indicating whether (user) should be +subscribed to or not. The server will respond with JSON failure if the +request is unauthorized or if the user doesn't exist. The server will +respond with JSON success after the subscription request is successfully +registered.

    /feed - Get updates for subscribed users

    +
    authorization

    POST to /feed, with a username parameter and an auth cookie. The server will respond with a JSON list of the last 50 updates from all subscribed users, in reverse chronological order. Fetching -/feed resets the new message count returned from /feedinfo. +/feed does not reset the new message count returned from /status. To do +that, look at POST /status.

    NOTE: subscription notifications are only stored while subscriptions are active. Any records inserted before or after a subscription is active will not show up in /feed. -

    /feedinfo, /feedinfo/(user) - Get subscription -status for a user

    +

    /status, /status/(user) - Get or clear +general and user-specific status

    +
    authorization
    -

    POST to /feedinfo with a username parameter and an auth -cookie to get general information about your subscribed feeds. -Currently, this only tells you how many new records there are since the -last time /feed was fetched. The server will respond with a JSON -object: +

    GET to /status to get information about your account. It tells you +the number of new subscription records since the last time the +subscription counter was reset, and a flag for whether the account was +mentioned since the last time the mention flag was cleared. The server +will respond with a JSON object: 

    -{"new":3}
+{
+  "feed_new": 3,
+  "mentioned": false
+}
    -

    POST to /feedinfo/(user) with a username parameter and -an auth cookie, where (user) is a user whose subscription status you are -interested in. The server will respond with a simple JSON object: +

    POST to /status with a clear parameter that is either +"feed" or "mentioned" to reset either the subscription counter or the +mention flag, respectively. There is not currently a way to clear both +with a single request. The server will respond with JSON success. + +

    GET to /status/(user) to get subscription information for a +particular user. The server will respond with a simple JSON object: 

     {"subscribed":true}
@@ -380,14 +401,15 @@ interested in.  The server will respond with a simple JSON object:
 the subscription status.
 
 
    /passwd - Change a user's password
    
+
    authorization
    
 
-
    POST to /passwd with a username parameter and an auth
-cookie, plus password and new_password
-parameters to change the user's password.  For extra protection,
-changing a password requires sending the user's current password in the
-password parameter.  If authentication is successful and
-the password matches, the user's password is set to
-new_password and the server responds with JSON success.
+
    POST to /passwd with password and
+new_password parameters to change the user's password.  For
+extra protection, changing a password requires sending the user's
+current password in the password parameter.  If
+authentication is successful and the password matches, the user's
+password is set to new_password and the server responds
+with JSON success.
 
 If the password doesn't match, or one of password or
 new_password are missing, the server returns JSON failure.
@@ -400,7 +422,7 @@ If the password doesn't match, or one of password or
 called blerg.a.  It's not designed to be public or
 installed with `make install-environment`, but it should be relatively
 straightforward to use it in C programs.  Look at the headers under the
-databse directory.
+database directory.
 
 
    A secondary library called blerg_auth.a handles the
 authentication layer of Blërg.  To use it, look at
-- 
2.25.1