API version 2.0

The 2.x API provides a set of RESTish endpoints which expose the non-administrator functionality of the system.

This is intended for use by developers building alternative front-ends to the Dialogue platform. It is not intended as a general purpose API for fetching information and statistics, for that please use the simpler 1.x interface.

Using the API

Endpoints are be accessed by the combination of URL and request method.

The result of a response may be determined by inspecting its status code. Those in the 2XX or 3XX ranges were successful whereas those in the 4XX or 5XX ranges were rejected due to either malformed data or server error.

Responses are returned in JSON format. Where possible, unsuccessful requests will return a body with a message key containing a human readable explanation for the error and may also include a data key containing exception specific information. In rare circumstances the body of a failed request may not be valid JSON - check the return code before attempting to decode the body.

Content

In almost all cases the content returned from the API should be treated as plain text and should never be inserted unescaped into an HTML document. There are three exceptions to this, the what and why fields of ideas an the body field of a challenge which may all return HTML with varying degrees of filtering already in place.

Endpoints

Challenges

Challenge list

GET /discussions

Return headings and summaries for all the currently public challenges. Note that this never includes private challenges.

Note: The body field may contain administrator specified unescaped and unfiltered HTML.

Example response:

[
   {
      "body":"",
      "summary":"Summarise this!",
      "id":"new-challenge-71885",
      "title":"New challenge 71885"
   },
   {
      "body":"<p>Hey there's some information here</p>\r\n",
      "summary":"A challenge about sheeps",
      "id":"sheep",
      "title":"Sheep"
   },
   {
      "body":"",
      "summary":"",
      "id":"ideas",
      "title":"Ideas"
   }
]

Search

Search all challenges

POST /search

Return metadata (title, comment count, ratings etc) for all matching ideas in all challenges.

Note: This also works as a GET request. When no (or blank) parameters are provided all ideas are returned. When searching for multiple tags, ideas matching any of the provided tags are returned. When searching for both text and tags ideas matching both the text and any of the tags are returned. By default ideas are returned in descending order of creation date (i.e. most recent first).

Parameters:

text: (optional) Matches against title, what, why, comments and tags
tags: (optional) One or more tags, comma separated.
sort: (optional) Sort field, may be one of created, rating or comments
order: (optional) Sort order, may be one of ascending or descending

Example response:

[
   {
      "average_rating":5.0,
      "ratings":1,
      "state":"new",
      "author":"AlanH",
      "title":"My tea-riffic idea",
      "discussion":"ideas",
      "tags":2,
      "id":"my-tea-riffic-idea-1",
      "comments":1,
      "created":"2014-02-19T16:03:01+00:00"
   }
]