timestamper/doc/api.rst

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.

List Events
-----------

``/<user-id>/<timeline-id>/list``
---------------------------------

GET
~~~