X-Git-Url: http://git.bytex64.net/?a=blobdiff_plain;f=www%2Fdoc%2Findex.html;h=947c373582d8232798564520c7ba4ab01ad8e9cf;hb=fd4abb4a961a1cfe8ebe1fa0b2a0987dc2f90b35;hp=3d40ad06596fe419dd24344012982e63be5f7ef1;hpb=6ce5fb7ab6e31f76e57639e4d04e32af33e77ee6;p=blerg.git diff --git a/www/doc/index.html b/www/doc/index.html index 3d40ad0..947c373 100644 --- a/www/doc/index.html +++ b/www/doc/index.html @@ -6,17 +6,45 @@
-There's no stable release, yet, but you can get everything currently running on blerg.dominionofawesome.com by cloning the git repository at http://git.bytex64.net/blerg.git. -
Blërg has varying requirements depending on how you want to run it — as a standalone HTTP server, or as a CGI. You will need: @@ -39,7 +67,7 @@ sense of humor, requires ruby to compile)
I know I'm gonna get shit for not using an autoconf-based system, but I really didn't want to waste time figuring it out. You should edit @@ -52,7 +80,7 @@ makefile refuses to work with BSD make. If you have patches or suggestions on how to make Blërg more portable, I'd be happy to hear them. -
At this point, it should be gravy. Type 'make' and in a few seconds,
you should have http_blerg
, cgi_blerg
,
@@ -60,7 +88,7 @@ you should have http_blerg
, cgi_blerg
,
individually as well, if you, for example, don't want to install the
prerequisites for http_blerg
or cgi_blerg
.
-
While it's not required, Blërg will be easier to set up if you configure it to work from the root of your website. For this reason, @@ -93,15 +121,153 @@ feeds for users. Install this like the CGI version above (on my server, it's at /rss.cgi). -
Blërg's API was designed to be as simple as possible. Data sent from +the client is POSTed with the application/x-www-form-urlencoded +encoding, and a successful response is always JSON. The API endpoints +will be described as though the server were serving requests from the +root of the wesite. + +
On failure, all API calls return either a standard HTTP error +response, like 404 Not Found if a record or user doesn't exist, or a 200 +response with some JSON indicating failure, which will look like this: + +
{"status": "failure"}
+
+
Blërg doesn't currently explain why there is a failure, and +I'm not sure it ever will. + +
On success, you'll either get some JSON relating to your request (for +/get, /tag, or /info), or a JSON object indicating success (for /create, +/put, /login, or /logout), which looks like this: + +
{"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), +or maybe a 502 Bad Gateway if you have it behind another web server. + +
All usernames must be 32 characters or less. Usernames must contain
+only the ASCII characters 0-9, A-Z, a-z, underscore (_), period (.),
+hyphen (-), single quote ('), and space ( ). Passwords can be at most
+64 bytes, and have no limits on characters (but beware: if you have a
+null in the middle, it will stop checking there 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, hyphen (-), and underscore (_). + +
To create a user, POST to /create with username
and
+password
parameters for the new user. The server will
+respond with failure if the user exists, or if the user can't be created
+for some other reason. The server will respond with success if the user
+is created.
+
+
POST to /login with the username
and
+password
parameters for an existing user. The server will
+respond with failure if the user does not exist or if the password is
+incorrect. On success, the server will respond with success, and will
+set a cookie named 'auth' that must be sent by the client when accessing
+restricted API functions (/put and /logout).
+
+
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 failure if the user does not exist or if the auth cookie is bad.
+The server will respond with success after the user is successfully
+logged out.
+
+
POST to /put with username
and data
+parameters, and an auth cookie. The server will respond with 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 success after the record is
+successfully added.
+
+
A GET request to /get/(user), where (user) is the user desired, will +return the last 50 records for that user in a list of objects. The +record objects look like this: + +
+{ + "record":"0", + "timestamp":1294309438, + "data":"eatin a taco on fifth street" +} ++ +
record
is the record number, timestamp
is
+the UNIX epoch timestamp (i.e., the number of seconds since Jan 1 1970
+00:00:00 GMT), and data
is the content of the record. The
+record number is sent as a string because while Blërg supports record
+numbers up to 264 - 1, Javascript uses floating point for all
+its numbers, and can only support integers without truncation up to
+253. This difference is largely academic, but I didn't want
+this problem to sneak up on anyone who is more insane than I am. :]
+
+
The second form, /get/(user)/(start record)-(end record), retrieves a +specific range of records, from (start record) to (end record) +inclusive. You can retrieve at most 100 records this way. If (end +record) - (start record) specifies more than 100 records, the server +will respond with JSON failure. + +
A GET request to /info/(user) will return a JSON object with +information about the user (currently only the number of records). The +info object looks like this: + +
+{ + "record_count": "544" +} ++ +
Again, the record count is sent as a string for 64-bit safety. + +
A GET request to this endpoint will return the last 50 records
+associated with the given tag. The first character is either # or H for
+hashtags, or @ for mentions (I call them ref tags). You should URL
+encode the # or @, lest some servers complain at you. The H alias for #
+was created because Apache helpfully strips the fragment of a URL
+(everything from the # to the end) before handing it off to the CGI,
+even if the hash is URL encoded. The record objects also contain an
+extra author
field, like so:
+
+{
+ "author":"Jon",
+ "record":"57",
+ "timestamp":1294555793,
+ "data":"I'm taking #garfield to the vet."
+}
+
+
There is currently no support for getting more than 50 tags, but /tag +will probably mutate to work like /get. + +
Blërg was created as the result of a thought experiment: "What if Twitter didn't need thousands of servers? What if its millions of users could be handled by a single highly efficient server?" This is probably an unreachable goal due to the sheer amount of I/O, but we could -certainly do better. Blërg was designed with very simple requirements: +certainly do better. Blërg was thus designed as a system with very +simple requirements:
And to further simplify, I didn't bother handling deletes, full text search, or more complicated tag searches. Blërg only does the basics. -
Classical model |
---|