98 lines
2.1 KiB
ReStructuredText
98 lines
2.1 KiB
ReStructuredText
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.
|
|
|
|
Events: ``/<user-id>/<timeline-id>/events``
|
|
-------------------------------------------
|
|
|
|
GET
|
|
~~~
|
|
|
|
PUT
|
|
~~~
|