188 lines
4.1 KiB
ReStructuredText
188 lines
4.1 KiB
ReStructuredText
API
|
||
====
|
||
|
||
The Isso API uses HTTP and JSON as primary communication protocol.
|
||
|
||
.. contents::
|
||
:local:
|
||
|
||
|
||
JSON format
|
||
-----------
|
||
|
||
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:: json
|
||
|
||
{
|
||
"id": 1,
|
||
"parent": null,
|
||
"text": "<p>Hello, World!</p>\n",
|
||
"mode": 1,
|
||
"hash": "4505c1eeda98",
|
||
"author": null,
|
||
"website": null,
|
||
"created": 1387321261.572392,
|
||
"modified": null,
|
||
"likes": 3,
|
||
"dislikes": 0
|
||
}
|
||
|
||
id :
|
||
comment id (unique per website).
|
||
|
||
parent :
|
||
parent id reference, may be ``null``.
|
||
|
||
text :
|
||
required, comment written in Markdown.
|
||
|
||
mode :
|
||
* 1 – accepted
|
||
* 2 – in moderation queue
|
||
* 4 – deleted, but referenced.
|
||
|
||
hash :
|
||
user identication, used to generate identicons. PBKDF2 from email or IP
|
||
address (fallback).
|
||
|
||
author :
|
||
author's name, may be ``null``.
|
||
|
||
website :
|
||
author's website, may be ``null``.
|
||
|
||
likes :
|
||
upvote count, defaults to 0.
|
||
|
||
dislikes :
|
||
downvote count, defaults to 0.
|
||
|
||
created :
|
||
time in seconds since UNIX time.
|
||
|
||
modified :
|
||
last modification since UNIX time, may be ``null``.
|
||
|
||
|
||
List comments
|
||
-------------
|
||
|
||
List all publicly visible comments for thread `uri`:
|
||
|
||
.. code-block:: text
|
||
|
||
GET /?uri=%2Fhello-world%2F
|
||
|
||
uri :
|
||
URI to fetch comments for, required.
|
||
|
||
plain :
|
||
pass plain=1 to get the raw comment text, defaults to 0.
|
||
|
||
|
||
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).
|
||
|
||
.. 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
|
||
}
|
||
|
||
The payload must be valid JSON. To prevent CSRF attacks, you must set the
|
||
`Content-Type` to `application/json` or omit the header completely.
|
||
|
||
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:
|
||
|
||
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
|
||
-----------------
|
||
|
||
Counts all publicly visible comments for thread `uri`:
|
||
|
||
.. code-block:: text
|
||
|
||
GET /count?uri=%2Fhello-world%2F
|
||
2
|
||
|
||
uri :
|
||
URI to count comments for, required.
|
||
|
||
returns an integer
|
||
|