This work is licensed under a Creative Commons Attribution 4.0 International License.
Static blogs and websites generated via Octopress, Jekyll, et al. generally incorporate comments using third party services and APIs. This means that reader generated content must be stored with a third party which may not be desirable to site maintainers who wish to keep all content under their control. While many hosted solutions exist to solve this problem, they all use different APIs which may not be well documented and require writing new plugins or scripts if the site maintainer decides to change comment providers in the future.
I propose a universal API for comment servers which, once implemented by a blog or site, can be used independently of the comment service (so long as the service also implements the API).
The API was designed with three goals in mind:
- Remain simple
- Easy implementation for servers and clients alike
- Allow light weight servers for static sites with static comments
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Services conforming to this specification MUST implement the following HTTP methods:
GET /$URI/comments[.json]
HEAD /$URI/comments[.json]
Returns comments associated with the given URI serialized as JSON (unless using HEAD). If no comments are associated with the URI servers MUST return 404 Not Found. Any JSON that is returned MUST adhere to the comments schema. Servers MAY choose to include the OPTIONAL HTTP header: Num-Comments set to the total number of comments for the given URI (including all replies, if supported).
POST /$URI/comment
Posts a new comment to the comments associated with the given URI. The body of a successful response MUST contain JSON which conforms to the comment JSON schema. Authentication is not covered by this specification, but clients and servers MAY choose to implement authentication of their choosing if they so desire. If the in_reply_to_comment_id parameter is provided and no comment with the given ID exists, servers SHOULD NOT include the reply_to parameter in the output JSON.
Parameters
- comment (REQUIRED)
- in_reply_to_comment_id (OPTIONAL)
OPTIONS /$URI/comment
OPTIONS /$URI/comment/$commentID
Returns the methods available for comments. Useful for checking if deleting, editing, and/or fetching of individual comments is supported by the specific server.
Services implementing this specification MAY choose to implement the following methods:
GET /$URI/comment/$commentID[.json]
HEAD /$URI/comment/$commentID[.json]
Gets the individual comment. Servers implementing this method MUST add the comments length in characters/runes (not bytes) to the Comment-Length header. Successful responses MUST contain valid JSON which conforms to the comment schema.
PUT /$URI/comment/$commentID
If a PUT request is issued, the server MAY choose to modify the existing comment or create a new comment. If a new comment is created the server MAY use a different ID than the one specified by the user. Parameters are the same as those specified by the POST /$URI/comment method.
The following JSON schemas are referenced in other parts of this document.
{
"$schema":"http://json-schema.org/draft-04/schema#",
"id":"https://samwhited.com/schema#comment",
"type":"object",
"properties":{
"comment":{
"type":"string"
},
"id":{
"type":"string"
},
"reply-to":{
"description":"The comment ID that this comment is in reply to",
"type":"string"
}
},
"required":[
"comment",
"id"
]
}{
"$schema":"http://json-schema.org/draft-04/schema#",
"id":"https://samwhited.com/schema#comments",
"type":"object",
"additionalProperties":false,
"properties":{
"comments":{
"type":"array",
"minItems":1,
"items":{
"$ref":"https://samwhited.com/schema#comment"
}
}
},
"required":[
"comments"
]
}