From 1153b9cf6e07b19200f7b5373fbfc236f6d947a1 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Wed, 18 Dec 2013 14:11:18 +0100 Subject: [PATCH] extend API documentation --- docs/docs/extras/api.rst | 179 ++++++++++++++++++++++++++++----------- 1 file changed, 129 insertions(+), 50 deletions(-) diff --git a/docs/docs/extras/api.rst b/docs/docs/extras/api.rst index 281f836..4255270 100644 --- a/docs/docs/extras/api.rst +++ b/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": "

Hello, World!

\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": "

Hello, World!

\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 +----------------- + +...