Update docs for API changes

diff --git a/www/css/doc.css b/www/css/doc.css
index 1173b95..adfe20c 100644 (file)
--- 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 (file)
--- a/www/doc/index.html
+++ b/www/doc/index.html
@@ -30,6 +30,7 @@ C.
   <li><a href="#api">API</a>
     <ul>
       <li><a href="#api_definitions">API Definitions</a></li>
+      <li><a href="#api_authorization">Authorizaton</a></li>
       <li><a href="#api_create">/create - create a new user</a></li>
       <li><a href="#api_login">/login - log in</a></li>
       <li><a href="#api_logout">/logout - log out</a></li>
@@ -38,9 +39,8 @@ C.
       <li><a href="#api_info">/info/(user) - Get information about a user</a></li>
       <li><a href="#api_tag">/tag/(#|H|@)(tagname) - Retrieve records containing tags</a></li>
       <li><a href="#api_subscribe">/subscribe/(user) - Subscribe to a user's updates</a></li>
-      <li><a href="#api_unsubscribe">/unsubscribe/(user) - Unsubscribe from a user's updates</a></li>
       <li><a href="#api_feed">/feed - Get updates for subscribed users</a></li>
-      <li><a href="#api_feedinfo">/feedinfo, /feedinfo/(user) - Get subscription status</a></li>
+      <li><a href="#api_status">/status, /status/(user) - Get or clear general and user-specific status</a></li>
       <li><a href="#api_passwd">/passwd - Change a user's password</a></li>
     </ul>
   </li>
@@ -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:
 
-<p><code>{"status": "failure"}</code>
+<pre>{"status": "failure"}</pre>
 
 <p>Blërg doesn't currently explain <i>why</i> 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:
 
-<p><code>{"status": "success"}</code>
+<pre>{"status": "success"}</pre>
 
 <p>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 <code>strncmp(3)</code> to compare).
 <p>Tags must be 64 characters or less, and can contain only the ASCII
 characters 0-9, A-Z, a-z, underscore (_), and hyphen (-).
 
+<h3><a name="api_authorization">Authorization</a></h3>
+
+<p>As the result of a successful <a href="#api_login">login</a>, the server
+will send back a cookie named <code>auth</code>.  This cookie authorizes
+restricted requests, and must be sent for any API endpoint marked <span
+class="feature">authorization</span>, 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.
+
 <h3><a name="api_create">/create</a> - create a new user</a></h3>
 
 <p>To create a user, POST to /create with <code>username</code> 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 <a
+href="#api_authorization">Authorization</a> above).
 
 <h3><a name="api_logout">/logout</a> - log out</a></h3>
+<div class="feature">authorization</div>
 
-<p>POST to /logout with with <code>username</code>, 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.
+<p>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.
 
 <h3><a name="api_put">/put</a> - add a new record</a></h3>
+<div class="feature">authorization</div>
 
-<p>POST to /put with <code>username</code> and <code>data</code>
-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
-<code>data</code> contains more than 65535 bytes <i>after</i> URL
-decoding.  The server will respond with JSON success after the record is
-successfully added.
+<p>POST to /put with a <code>data</code> parameter.  The server will
+respond with JSON failure if the request is unauthorized, if the user
+doesn't exist, or if <code>data</code> contains more than 65535 bytes
+<i>after</i> URL decoding.  The server will respond with JSON success
+after the record is successfully added.
 
 <h3><a name="api_get">/get/(user), /get/(user)/(start record)-(end record)</a> - get records for a user</a></h3>
 
@@ -332,45 +346,52 @@ will probably mutate to work like /get.
 
 <h3><a name="api_subscribe">/subscribe/(user)</a> - Subscribe to a
 user's updates</a></h3>
+<div class="feature">authorization</div>
 
-<p>POST to /subscribe/(user) with a <code>username</code> 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.
-
-<h3><a name="api_unsubscribe">/unsubscribe/(user)</a> - Unsubscribe from
-a user's updates</h3>
-
-<p>Identical to /subscribe, but removes the subscription.
+<p>POST to /subscribe/(user) with a <code>subscribed</code> 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.
 
 <h3><a name="api_feed">/feed</a> - Get updates for subscribed users</h3>
+<div class="feature">authorization</div>
 
 <p>POST to /feed, with a <code>username</code> 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 <a href="#api_status">POST /status</a>.
 
 <p>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.
 
-<h3><a name="api_feedinfo">/feedinfo, /feedinfo/(user)</a> - Get subscription
-status for a user</a></h3>
+<h3><a name="api_status">/status, /status/(user)</a> - Get or clear
+general and user-specific status</a></h3>
+<div class="feature">authorization</div>
 
-<p>POST to /feedinfo with a <code>username</code> 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:
+<p>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:
 
 <pre>
-{"new":3}
+{
+  "feed_new": 3,
+  "mentioned": false
+}
 </pre>
 
-<p>POST to /feedinfo/(user) with a <code>username</code> 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:
+<p>POST to /status with a <code>clear</code> 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.
+
+<p>GET to /status/(user) to get subscription information for a
+particular user.  The server will respond with a simple JSON object:
 
 <pre>
 {"subscribed":true}
@@ -380,14 +401,15 @@ interested in.  The server will respond with a simple JSON object:
 the subscription status.
 
 <h3><a name="api_passwd">/passwd</a> - Change a user's password</a></h3>
+<div class="feature">authorization</div>
 
-<p>POST to /passwd with a <code>username</code> parameter and an auth
-cookie, plus <code>password</code> and <code>new_password</code>
-parameters to change the user's password.  For extra protection,
-changing a password requires sending the user's current password in the
-<code>password</code> parameter.  If authentication is successful and
-the password matches, the user's password is set to
-<code>new_password</code> and the server responds with JSON success.
+<p>POST to /passwd with <code>password</code> and
+<code>new_password</code> parameters to change the user's password.  For
+extra protection, changing a password requires sending the user's
+current password in the <code>password</code> parameter.  If
+authentication is successful and the password matches, the user's
+password is set to <code>new_password</code> and the server responds
+with JSON success.
 
 If the password doesn't match, or one of <code>password</code> or
 <code>new_password</code> are missing, the server returns JSON failure.
@@ -400,7 +422,7 @@ If the password doesn't match, or one of <code>password</code> or
 called <code>blerg.a</code>.  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
-<code>databse</code> directory.
+<code>database</code> directory.
 
 <p>A secondary library called <code>blerg_auth.a</code> handles the
 authentication layer of Blërg.  To use it, look at