API Documentation

The threaded discussion provides the following RESTful API to support development of various types of UI

Authentication

Basic HTTP Auth - username, password

If credentials are present and valid, the user context will be used to execute the request. If Basic HTTP Auth header is not set, the code will check for cookies user2 and auth_cookie2. If present, they will be used to determine user context.

Most GET methods do not require authentication, but take into account the user context. All POST and PUT methods require authentication.

Methods

GET http://serverURL**/api/threads** - returns the JSON list of first 51 top level thread titles. Optional parameters:
1. id - max thread ID to return (inclusive)
2. count - number of threads to return
GET http://serverURL**/api/threads/[id]** (where [id] is the top level thread ID) - returns the top level thread and all nested replies in a tree-structured JSON.
GET http://serverURL**/api/messages/[id]** (where [id] is the message ID) - returns the message title, body, author, views, likes, dislikes, parent message ID, etc.
GET http://serverURL**/api/messages/[id]/answers** - returns the answers to the message with the given ID (one level).
GET http://serverURL**/api/messages** - returns the messages that match the given criteria. Parameters:
1. mode - supported values are "bydate" (default value), "mymessages" and "answered".
2. id - max message ID to return (inclusive). default value is -1 (latest message)
3. count - number of messages to return. default is 30 for "bydate" mode and 0 for "answered". the latter means "all messages since the last check" (the last message ID is stored in a cookie).

GET http://serverURL**/api/profile**

Returns user profile

Example of the data returned:

{
  "id": 1020,
  "name": "test",
  "new_pm": 19,
  "banned": false,
  "ban_ends": null,
  "ban_time": false,
  "prop_bold": false,
  "prop_tz": -5
}

PUT http://serverURL**/api/messages/$id/like**

Like the message
DELETE http://serverURL**/api/messages/$id/like**

Dislike the message

Both methods return the new value of "likes" for the specified message given by the user:

  {
    "value": -1
  }

PUT http://serverURL**/api/messages/$id/bookmark**

Bookmark the message
DELETE http://serverURL**/api/messages/$id/bookmark**

Remove the bookmark
POST http://serverURL**/api/threads**

Creates new thread. See below for details.
POST http://serverURL**/api/messages/$id/answers**

Creates a response to the specified message.
PUT http://serverURL**/api/messages/$id**

Updates the message

For three methods above, the request must contain JSON object with the following values:

  {"subject":"subject goes here", "body":"this is a message body", "ticket":"some unique string to prevent duplicates", "nsfw":true}

The last two parameters are optional

All three functions return JSON object with "id" property of an object created (thread or message) if successful, or status 400 in case of an error.

Reactions

GET http://serverURL**/api/reactions**

Returns a list of labels and image URLs for configured reactions.
PATCH http://serverURL**/api/messages/$id/reactions/$reaction**

Toggle a reaction. A new reaction replaces the old one. Returns current list of reactions and user ratings.

Private mail

GET http://serverURL**/api/inbox** (optional parameters: count, id)
GET http://serverURL**/api/inbox/$id**
GET http://serverURL**/api/sent** (optional parameters: count, id)
GET http://serverURL**/api/sent/$id**
POST http://serverURL**/api/sent** (payload - JSON object with subject, body, ticket and recipient fields)

Examples

<html><head>
<script src="js/jquery-1.10.2.min.js"></script>
<script language="javascript">

function sendRequest(username, password) {
  $.ajax
    ({
      type: "GET",
      url: "api/profile",
      dataType: 'json',
      async: false,
      beforeSend: function (xhr) {
          xhr.setRequestHeader ("Authorization", "Basic " + btoa(username + ":" + password));
      },    
      success: function (data){
      alert('Thanks you, ' + data.name + '!'); 
      }
  });
}
</script></head>
<body onload="sendRequest('test', 'test');"/>
</html>

Another example for posting a reply into the thread: The site is at http://myKitchen.com/ The original message ID is 00001111

Here how the call is going to look like (tested with JQuery, Intel App Framework)

function sendReply()
{
   var url "http://myKitchen.com/api/messages/00001111/answers";    
    $.post
    (url,
        JSON.stringify({
            "subject":"subject goes here", 
            "body":"this is a message body", 
            "ticket":"blah", 
            "nsfw":false
        }),
        function(data, status)
        {
            alert("yay! posted!");
        }
    );    
}

Provide feedback

Saved searches