Beginning API documentation.

.gitignore

@@ -0,0 +1 @@
+*.sw?

doc/api.rst

@@ -0,0 +1,90 @@
+TimeStamper Web Service API
+===========================
+
+This document describes the REST API the TimeStamper web service exposes.
+
+General Assumptions and Definitions
+-----------------------------------
+
+Values that vary are notated using typeset in *emphasized text* when they
+appear in the text of the documentation and are ``<enclosed by angle
+brackets>`` when they appear in code examples or other monospaced text.
+
+Paths in this document are relative to the server root. So
+``/<user-id>/current`` refers to ``http://sub.domain.tld/<user-id>/current``
+
+Any paths inteded to be interpreted differently will use the full, absolute
+form (ie. ``http://www.twitter.com/bob``)
+
+User Management: ``/<user-id>``
+-------------------------------
+
+All requests directed at the user id URL are related to user management. The
+request is further interpreted by the request type. This resource responds to
+the ``GET``, ``POST``, ``PUT``, and ``DELETE`` HTTP verbs.
+
+*user-id*:
+    The user identifier, or username. This is a string value; valid characters
+    are ``[a-zA-Z0-9_]``.
+
+PUT
+~~~
+
+Create a new user. A new user is created only if there is not an existing user
+with the same *user-id*. If
+
+Returns:
+    * ``201 Created`` if the user was successfully created.
+    * ``409 Conflict`` if a user already exists for this *user-id*.
+
+.. TODO: input format, preconditions, other returns
+
+GET
+~~~
+
+Returns the information about the user for *user-id*.
+
+Return:
+    * ``200 OK``
+    * ``404 Not Found`` if there is no user for *user-id*.
+
+POST
+~~~~
+
+Updates information about the user for *user-id*.
+
+DELETE
+~~~~~~
+
+Deletes the user for *user-id*.
+
+Timelines: ``/<user-id>/<timeline-id>``
+---------------------------------------
+
+*user-id*:
+    See `User Management`_.
+
+*timeline-id*:
+    A timeline identifier. A string; valid characters are ``[a-zA-Z0-9_]``.
+
+GET
+~~~
+
+Returns the timeline meta-data.
+
+POST
+~~~~
+
+Update timeline meta-data.
+
+PUT
+~~~
+
+Create a new timeline.
+
+DELETE
+~~~~~~
+
+Delete a timeline.
+
+

doc/sampl-urls.txt

@@ -0,0 +1,8 @@
+/jdbernard -- information about the user 'jdbernard'
+/jdbernard/work -- information about the 'work' timeline
+/jdbernard/work/events -- list events in the timeline
+
+/jdbernard/timelines -- list all timelines for the user
+/jdbernard/timelines/work -- list information about the 'work' timeline
+
+/jdbernard/events/work -- list all events for the 'work' timeline