extend API documentation

docs/docs/extras/api.rst

@@ -1,98 +1,177 @@
-Isso API
-========
+API
+====
 
 The Isso API uses HTTP and JSON as primary communication protocol.
 
+.. contents::
+    :local:
+
+
 JSON format
 -----------
 
-When querying the API you either get an error, an object or list of
-objects representing the comment. Here's a example JSON returned from
+When querying the API you either get a regular HTTP error, an object or list of
+objects representing the comment. Here's an example JSON returned from
 Isso:
 
-.. code-block:: js
+.. code-block:: json
 
     {
-        "text": "Hello, World!",
-        "author": "Bernd",
-        "website": null,
-        "votes": 0,
-        "mode": 1,
         "id": 1,
         "parent": null,
-        "hash": "68b329da9893e34099c7d8ad5cb9c940",
-        "created": 1379001637.50,
-        "modified": null
+        "text": "<p>Hello, World!</p>\n",
+        "mode": 1,
+        "hash": "4505c1eeda98",
+        "author": null,
+        "email": null,
+        "website": null
+        "created": 1387321261.572392,
+        "modified": null,
+        "likes": 3,
+        "dislikes": 0,
     }
 
-text : required, comment as HTML
+id :
+    comment id (unique per website).
 
-author : author's name, may be ``null``
+parent :
+    parent id reference, may be ``null``.
 
-website : author's website, may be ``null``
+text :
+    required, comment written in Markdown.
 
-votes : sum of up- and downvotes, defaults to zero.
+mode :
+    * 1 – accepted
+    * 2 – in moderation queue
+    * 4 – deleted, but referenced.
 
-mode : \* 1, accepted comment \* 2, comment in moderation queue \* 4,
-comment deleted, but is referenced
+hash :
+    user identication, used to generate identicons. PBKDF2 from email or IP
+    address (fallback).
 
-id : unique comment number per thread
+author :
+    author's name, may be ``null``.
 
-parent : answer to a parent id, may be ``null``
+website :
+    author's website, may be ``null``.
 
-hash : user identification, used to generate identicons
+likes :
+    upvote count, defaults to 0.
 
-created : time in seconds sinde epoch
+dislikes :
+    downvote count, defaults to 0.
+
+created :
+    time in seconds since UNIX time.
+
+modified :
+    last modification since UNIX time, may be ``null``.
 
-modified : last modification time in seconds, may be ``null``
 
 List comments
 -------------
 
-List all visible comments for a thread. Does not include deleted and
-comments currently in moderation queue.
+List all publicely visible comments for thread `uri`:
 
-    GET /?uri=path
+.. code-block:: text
 
-You must encode ``path``, e.g. to retrieve comments for
-``/hello-world/``:
+    GET /?uri=%2Fhello-world%2F
 
-::
+uri :
+    URI to fetch comments for, required.
 
-    GET /?uri=%2Fhello-world%2F
+plain :
+    pass plain=1 to get the raw comment text, defaults to 0.
 
-To disable automatic Markdown-to-HTML conversion, pass ``plain=1`` to
-the query URL:
 
-::
+Create comment
+--------------
 
-    GET /?uri=...&plain=1
+To create a new comment, you need to issue a POST request to ``/new`` and add
+the current URI (so the server can check if the location actually exists).
 
-As response, you either get 200, 400, or 404, which are pretty
-self-explanatory.
+.. code-block:: bash
 
-::
+    $ curl -vX POST http://isso/new?uri=%2F -d '{"text": "Hello, World!"}' -H "Content-Type: application/json"
+    < HTTP/1.1 201 CREATED
+    < Set-Cookie: 1=...; Expires=Wed, 18-Dec-2013 12:57:20 GMT; Max-Age=900; Path=/
+    {
+        "author": null,
+        "created": 1387370540.733824,
+        "dislikes": 0,
+        "email": null,
+        "hash": "6dcdbfb4f00d",
+        "id": 1,
+        "likes": 0,
+        "mode": 1,
+        "modified": null,
+        "parent": null,
+        "text": "<p>Hello, World!</p>\n",
+        "website": null
+    }
 
-    GET /
-    400 BAD REQUEST
+The payload must be valid JSON. To prevent CSRF attacks, you must set the
+`Content-Type` to `application/json` or omit the header completely.
 
-    GET /?uri=%2Fhello-world%2F
-    404 NOT FOUND
+The server issues a cookie per new comment which acts as authentication token
+to modify or delete your own comment. The token is cryptographically signed
+and expires automatically after 900 seconds by default.
 
-    GET /?uri=%2Fcomment-me%2F
-    [{comment 1}, {comment 2}, ...]
+The following keys can be used to POST a new comment, all other fields are
+dropped or replaced with values from the server:
 
-Create comments
----------------
+text : String
+    Actual comment, at least three characters long, required.
 
-...
+author : String
+    Comment author, optional.
 
-Delete comments
----------------
+website : String
+    Commenter's website (currently no field available in the client JS though),
+    optional.
+
+email : String
+    Commenter's email address (can be any arbitrary string though) used to
+    generate the identicon. Limited to 254 characters (RFC specification),
+    optional.
+
+parent : Integer
+    Reference to parent comment, optional.
+
+
+Edit comment
+------------
+
+When your authentication token is not yet expired, you can issue a PUT request
+to update `text`, `author` and `website`. After an update, you get an updated
+authentication token and the comment as JSON:
+
+.. code-block:: bash
+
+    $ curl -X PUT http://isso/id/1 -d "..." -H "Content-Type: application/json"
+
+
+Delete comment
+--------------
+
+You can delete your own comments when your authentication token (= cookie) is
+not yet expired:
+
+.. code-block:: bash
+
+    $ curl -X DELETE http://isso/id/1 -H "Content-Type: application/json"
+    null
+
+Returns either `null` or a comment with an empty text value when the comment
+is still referenced by other comments.
 
-...
 
 Up- and downvote comments
 -------------------------
 
 ...
+
+Get comment count
+-----------------
+
+...