extend API documentation
This commit is contained in:
Martin Zimmermann
parent
a728d3e32d
commit
1153b9cf6e
@ -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
|
||||
|
||||
You must encode ``path``, e.g. to retrieve comments for
|
||||
``/hello-world/``:
|
||||
|
||||
::
|
||||
.. code-block:: text
|
||||
|
||||
GET /?uri=%2Fhello-world%2F
|
||||
|
||||
To disable automatic Markdown-to-HTML conversion, pass ``plain=1`` to
|
||||
the query URL:
|
||||
uri :
|
||||
URI to fetch comments for, required.
|
||||
|
||||
::
|
||||
plain :
|
||||
pass plain=1 to get the raw comment text, defaults to 0.
|
||||
|
||||
GET /?uri=...&plain=1
|
||||
|
||||
As response, you either get 200, 400, or 404, which are pretty
|
||||
self-explanatory.
|
||||
Create comment
|
||||
--------------
|
||||
|
||||
::
|
||||
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).
|
||||
|
||||
GET /
|
||||
400 BAD REQUEST
|
||||
.. code-block:: bash
|
||||
|
||||
GET /?uri=%2Fhello-world%2F
|
||||
404 NOT FOUND
|
||||
$ 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 /?uri=%2Fcomment-me%2F
|
||||
[{comment 1}, {comment 2}, ...]
|
||||
The payload must be valid JSON. To prevent CSRF attacks, you must set the
|
||||
`Content-Type` to `application/json` or omit the header completely.
|
||||
|
||||
Create comments
|
||||
---------------
|
||||
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.
|
||||
|
||||
...
|
||||
The following keys can be used to POST a new comment, all other fields are
|
||||
dropped or replaced with values from the server:
|
||||
|
||||
Delete comments
|
||||
---------------
|
||||
text : String
|
||||
Actual comment, at least three characters long, required.
|
||||
|
||||
author : String
|
||||
Comment author, optional.
|
||||
|
||||
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
|
||||
-----------------
|
||||
|
||||
...
|
||||
|
||||
Loading…
Reference in New Issue
Block a user