Description

The described routes take care of the synchronization (create, update, delete) of SocialHub Comments.

Only comments of published SocialHub Posts can be synchronized.

If a user authenticated (logged in / registered) himself through a social network, it is possible to synchronize all comments which are created on the source site in a way that it appears the user commented directly on the social network he logged in from.
Currently only user access tokens of Facebook are allowed to be used, so you must specify FACEBOOK as networkType value for the given token.
If the token turns out to be invalid at the time the comment is published, it will instead be published like it would have been if there was no token at all.

Schema

{
    "description":"Representation of a SocialHub Comment entity",
    "type":"object",
    "properties":{
        "commentId":{
            "description":"the commentId as global unique id of the comment.",
            "type":"string",
            "required":false
        },
        "postId":{
            "description":"The unique postId of the SocialHub Post this comment belongs to",
            "type":"string",
            "required":true
        },
        "parentCommentId":{
            "description":"The unique commentId of the parent comment, if there is any",
            "type":"string",
            "required":false
        },
        "author":{
            "description":"The human readable name of the author",
            "type":"string",
            "required":true
        },
        "authorLink":{
            "description":"An absolute URL to the profile of the comments author",
            "type":"string",
            "format":"string",
            "required":false
        },
        "content":{
            "description":"The actual content of the comment",
            "type":"object",
            "required":true,
            "properties":{
                "plain":{
                    "description":"Comment content as plain text",
                    "type":"string",
                    "format":"string",
                    "required":true
                },
                "html":{
                    "description":"Comment content as raw HTML text",
                    "type":"string",
                    "format":"string",
                    "required":false
                }
            }
        },
        "token":{
            "description":"Network specific authentication token to publish this comment with",
            "type":"string",
            "required":false
        },
        "networkType":{
            "description":"The network the authentication token belongs to",
            "type":"string",
            "required":false
        }
    }
}

POST /comments

Create a new comment through SocialHub for the specified SocialHub Post.
You will get the SocialHub specific unique ID for the new comment as response.

Example request contents:

{
    "postId": "3f0a3592c510d50e0c5f65c22266f163",
    "author": "David Neuhaus",
    "authorLink": "http://example.com/node/1", 
    "content": {
      "plain": "This is absolutely insane!",
      "html": "<a href="http://socialhub.io">This</a> is absolutely insane!" 
    },
    "token": "usi73ds7a3592c51_sauds0d50e0c5f65c2_2266f163",
    "networkType": "FACEBOOK"
}

Example response:

{
    "commentId": "sd8sd7s7d7s9sghjktfggfdfd7sd67a9"
}

POST {postCommentCallback}

This is not a Publisher API route, but a route that would be implemented by the site which created the post.
If given, the SocialHub will make a POST request to the postCommentCallback-URL specified in the post-data, every time a new comment is created for the post.
Request contents are the same as on the POST /comments route.

Example request contents:

{
    "postId": "7utoegnuu0VyQrckgD9KXNaL5Lit0l5u",
    "author": "David Neuhaus",
    "authorLink": "http://plus.google.com/114199062289873621778",
    "created": "2005-08-15T15:52:01+0000",
    "content": {
      "plain": "This is absolutely insane!",
      "html": "<a href="http://socialhub.io">This</a> is absolutely insane!" 
    }
}

PUT /comments/{commentId}

Updates the specified existing SocialHub Comment and the comment on the social networks where possible.

Example request contents:

{
    "postId": "7utoegnuu0VyQrckgD9KXNaL5Lit0l5u",
    "content": {
      "plain": "This is absolutely insane: http://socialhub.io",
      "html": "This is absolutely insane: <a href="http://socialhub.io">http://socialhub.io</a>" 
    }
}

PUT {postCommentCallback}

This is not a Publisher API route, but a route that would be implemented by the site which created the post.
If given, the SocialHub will make a PUT request to the postCommentCallback-URL specified in the post-data, every time an existing comment of this post has been updated.
Request contents are the same as on the PUT /comments/{commentId} route.

Example request content:

{
    "commentId": "sd8sd7s7d7s9sghjktfggfdfd7sd67a9"
    "postId": "7utoegnuu0VyQrckgD9KXNaL5Lit0l5u",
    "content": {
      "plain": "This is absolutely insane: http://socialhub.io",
      "html": "This is absolutely insane: <a href="http://socialhub.io">http://socialhub.io</a>" 
    }
}

DELETE /comments/{commentId}

Deletes the specified SocialHub comment and the comment on the social networks where possible.

DELETE {postCommentCallback}

This is not a Publisher API route, but a route that would be implemented by the site which created the post.
If given, the SocialHub will make a DELETE request to the postCommentCallback-URL specified in the post-data, every time an existing comment of this post has been deleted.

Example request content:

{
    "commentId": "sd8sd7s7d7s9sghjktfggfdfd7sd67a9"
}