arno/isso
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

apidoc for "new comment"

Browse Source
This commit is contained in:
Joshua Gleitze 2016-06-03 10:13:13 +02:00
parent 5ca5d680fa
commit b2d9c80b5f
1 changed files with 64 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
isso/views/comments.py
View File

@ -60,6 +60,12 @@ def xhr(func):
not forged (XHR is restricted by CORS separately). not forged (XHR is restricted by CORS separately).
""" """
"""
@apiDefine csrf
@apiHeader {string="application/json"} Content-Type
The content type must be set to `application/json` to prevent CSRF attacks.
"""
def dec(self, env, req, *args, **kwargs): def dec(self, env, req, *args, **kwargs):
if req.content_type and not req.content_type.startswith("application/json"): if req.content_type and not req.content_type.startswith("application/json"):
@ -140,6 +146,64 @@ class API(object):
return True, "" return True, ""
"""
@api {post} /new create new
@apiGroup Comment
@apiUse csrf
@apiParam {string} uri
The uri of the thread to create the comment on.
@apiParam {string} text
The comment’s raw text.
@apiParam {string} [author]
The comment’s author’s name.
@apiParam {string} [email]
The comment’s author’s email address.
@apiParam {string} [website]
The comment’s author’s website’s url.
@apiParam {number} [parent]
The parent comment’s id iff the new comment is a response to an existing comment.
@apiExample {curl} Create a reply to comment with id 15:
curl 'https://comments.example.com/new?uri=/thread/' -d '{"text": "Stop saying that! *isso*!", "author": "Max Rant", "email": "rant@example.com", "parent": 15}' -H 'Content-Type: application/json'
@apiSuccess {number} id
The comment’s id (assigned by the server).
@apiSuccess {number} parent
Id of the comment this comment is a reply to. `null` if this is a top-level-comment.
@apiSuccess {number=1,2,4} mode
The comment’s mode:
value | explanation
--- | ---
`1` | accepted: The comment was accepted by the server and is published.
`2` | in moderation queue: The comment was accepted by the server but awaits moderation.
`4` | deleted, but referenced: The comment was deleted on the server but is still referenced by replies.
@apiSuccess {string} author
The comments’s author’s name or `null`.
@apiSuccess {string} website
The comment’s author’s website or `null`.
@apiSuccess {string} hash
A hash uniquely identifying the comment’s author.
@apiSuccess {number} created
UNIX timestamp of the time the comment was created (on the server).
@apiSuccess {number} modified
UNIX timestamp of the time the comment was last modified (on the server). `null` if the comment was not yet modified.
@apiSuccessExample Success after the above request:
{
"website": null,
"author": "Max Rant",
"parent": 15,
"created": 1464940838.254393,
"text": "<p>Stop saying that! <em>isso</em>!</p>",
"dislikes": 0,
"modified": null,
"mode": 1,
"hash": "e644f6ee43c0",
"id": 10,
"likes": 0
}
"""
@xhr @xhr
@requires(str, 'uri') @requires(str, 'uri')
def new(self, environ, request, uri): def new(self, environ, request, uri):