<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>
<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>
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.
/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),
<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
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>
<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}
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.
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