Web API

django-comments-xtd uses django-rest-framework to expose a Web API that provides developers with access to the same functionalities offered through the web user interface. The Web API has been designed to cover the needs required by the JavaScript plugin, and it’s open to grow in the future to cover additional functionalities.

There are 5 methods available to perform the following actions:

  1. Post a new comment.
  2. Retrieve the list of comments posted to a given content type and object ID.
  3. Retrieve the number of comments posted to a given content type and object ID.
  4. Post user’s like/dislike feedback.
  5. Post user’s removal suggestions.

Post a new comment

URL name: comments-xtd-api-create
Mount point: <comments-mount-point>/api/comment/
HTTP Methods: POST
HTTP Responses: 201, 202, 204, 403
Serializer: django_comments_xtd.api.serializers.WriteCommentSerializer

This method expects the same fields submitted in a regular django-comments-xtd form. The serializer uses the function django_comments.get_form to verify data validity.

Meaning of the HTTP Response codes:

  • 201: Comment created.
  • 202: Comment in moderation.
  • 204: Comment confirmation has been sent by mail.
  • 403: Comment rejected, as in Disallow black listed domains.

Retrieve comment list

URL name: comments-xtd-api-list
Mount point: <comments-mount-point>/api/<content-type>/<object-pk>/
<content-type> is a hyphen separated lowecase pair app_label-model
<object-pk> is an integer representing the object ID.
HTTP Methods: GET
HTTP Responses: 200
Serializer: django_comments_xtd.api.serializers.ReadCommentSerializer

This method retrieves the list of comments posted to a given content type and object ID:

$ http http://localhost:8000/comments/api/blog-post/4/

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Length: 2707
Content-Type: application/json
Date: Tue, 23 May 2017 11:59:09 GMT
Server: WSGIServer/0.2 CPython/3.6.0
Vary: Accept, Cookie
X-Frame-Options: SAMEORIGIN

[
    {
        "allow_reply": true,
        "comment": "Integer erat leo, ...",
        "flags": {
            "dislike": {
                "active": false,
                "users": []
            },
            "like": {
                "active": false,
                "users": [
                    "1:admin",
                    "5:alice",
                    "2:fulanito",
                    "4:joebloggs",
                    "3:menganito"
                ]
            },
            "removal": {
                "active": false,
                "count": null
            }
        },
        "id": 10,
        "is_removed": false,
        "level": 0,
        "parent_id": 10,
        "permalink": "/comments/cr/8/4/#c10",
        "submit_date": "May 18, 2017, 9:19 AM",
        "user_avatar": "http://www.gravatar.com/avatar/7dad9576 ...",
        "user_moderator": true,
        "user_name": "Joe Bloggs",
        "user_url": ""
    },
    {
        ...
    }
]

Retrieve comments count

URL name: comments-xtd-api-count
Mount point: <comments-mount-point>/api/<content-type>/<object-pk>/count/
<content-type> is a hyphen separated lowecase pair app_label-model
<object-pk> is an integer representing the object ID.
HTTP Methods: GET
HTTP Responses: 200
Serializer: django_comments_xtd.api.serializers.ReadCommentSerializer

This method retrieves the number of comments posted to a given content type and object ID:

$ http http://localhost:8000/comments/api/blog-post/4/count/

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Length: 11
Content-Type: application/json
Date: Tue, 23 May 2017 12:06:38 GMT
Server: WSGIServer/0.2 CPython/3.6.0
Vary: Accept, Cookie
X-Frame-Options: SAMEORIGIN

{
    "count": 4
}

Post like/dislike feedback

URL name: comments-xtd-api-feedback
Mount point: <comments-mount-point>/api/feedback/
HTTP Methods: POST
HTTP Responses: 201, 204, 403
Serializer: django_comments_xtd.api.serializers.FlagSerializer

This method toggles flags like/dislike for a comment. Successive calls set/unset the like/dislike flag:

$ http -a admin:admin POST http://localhost:8000/comments/api/feedback/ comment=10 flag="like"

HTTP/1.0 201 Created
Allow: POST, OPTIONS
Content-Length: 34
Content-Type: application/json
Date: Tue, 23 May 2017 12:27:00 GMT
Server: WSGIServer/0.2 CPython/3.6.0
Vary: Accept, Cookie
X-Frame-Options: SAMEORIGIN

{
    "comment": 10,
    "flag": "I liked it"
}

Calling it again unsets the “I liked it” flag:

$ http -a admin:admin POST http://localhost:8000/comments/api/feedback/ comment=10 flag="like"

HTTP/1.0 204 No Content
Allow: POST, OPTIONS
Content-Length: 0
Date: Tue, 23 May 2017 12:26:56 GMT
Server: WSGIServer/0.2 CPython/3.6.0
Vary: Accept, Cookie
X-Frame-Options: SAMEORIGIN

It requires the user to be logged in:

$ http POST http://localhost:8000/comments/api/feedback/ comment=10 flag="like"

HTTP/1.0 403 Forbidden
Allow: POST, OPTIONS
Content-Length: 58
Content-Type: application/json
Date: Tue, 23 May 2017 12:27:31 GMT
Server: WSGIServer/0.2 CPython/3.6.0
Vary: Accept, Cookie
X-Frame-Options: SAMEORIGIN

{
    "detail": "Authentication credentials were not provided."
}

Post removal suggestions

URL name: comments-xtd-api-flag
Mount point: <comments-mount-point>/api/flag/
HTTP Methods: POST
HTTP Responses: 201, 403
Serializer: django_comments_xtd.api.serializers.FlagSerializer

This method sets the removal suggestion flag on a comment. Once created for a given user successive calls return 201 but the flag object is not created again.

$ http POST http://localhost:8000/comments/api/flag/ comment=10 flag="report"

HTTP/1.0 201 Created
Allow: POST, OPTIONS
Content-Length: 42
Content-Type: application/json
Date: Tue, 23 May 2017 12:35:02 GMT
Server: WSGIServer/0.2 CPython/3.6.0
Vary: Accept, Cookie
X-Frame-Options: SAMEORIGIN

{
    "comment": 10,
    "flag": "removal suggestion"
}

As the previous method, it requires the user to be logged in.