Dialogue API 2.0

API version 2.0

The 2.x API provides a set of RESTish endpoints which expose details about public challenges.

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. Requests which take parameters should provide these url-encoded in the form body as you would if submitting an HTML form.

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 discussion which may all return HTML with varying degrees of filtering already in place.

Endpoints

Discussions

Discussion list

GET /discussions

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

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

Example response:

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

Search

Search all discussions

POST /search

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

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 matchingboth 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