Need help? Looking for tips and tricks?

This knowledge base contains loads of useful advice and answers to common questions.

If you're still stuck you can always submit a support request and we'll get back to you ASAP.

Dialogue API 2.0

Hamish Woodside -

API version 2.0

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

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 should include the API secret as described below and those 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.


Security

In order to access this API you need a secret. This may be configured by Delib on a per-site basis. All API requests must include this secret which should be included via basic authentication - use the username api and the API secret as the password.

As the secret allows access to potentially sensitive user information it should be protected accordingly. This includes using the API via SSL where possible.

Along with the API secret many of the endpoints require an end user to be logged in. Upon successful login the API consumer is provided with an __ac cookie. This should be forwarded as a cookie to all API requests. It's safe to pass this cookie on to the end user's browser.

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

Users

Register

POST /users

Create a new user.

Note: It's possible for site administrators to configure extra custom fields for user demographics. When configuring each of these fields an ID is assigned which is accepted here as a parameter. At present it is the responsibility of the consumer to ensure the values for any extra demographics are present and correct.

Parameters:

username
Login ID, must not include non-ascii characters
password
Password, must be at least five characters
email
Email address

Login

POST /users/login

Attempt to authenticate a user, and set an appropriate __ac cookie on the response if successful.

Note: Due to the way authentication interacts with the underlying framework, a successful response to this request will include a cookie rather than returned as a JSON structure. This cookie is safe to pass on to the end user's browser and should be included with all subsequent requests made by that user.

Parameters:

__ac_name
Login name for user
__ac_password
Plain text password

Logout

POST /users/logout

Log the current user out. Note that this may not invalidate the cookie and consumers may need to unset it on end user's browsers manually.

Generate password reset token

POST /users/password/reset

Start the password reset procedure for a given user.

Note: Never pass the token back to the requesting user directly as this would allow any user to reset any other user's password. Instead, fetch the user email address via the profile endpoint and send the token to them. To complete the process use the consume token endpoint described below.

Parameters:

username
User for whom we should generate a token

Example response:

{
   "token":"7202ad764627b352948ec3c2a9ba3e82",
   "expiry":"2014-02-26T15:44:28+00:00"
}

Consume password reset token

POST /users/password/reset/consume

Complete the password reset procedure for a given user.

Parameters:

username
User for to change (must match user used to generate token)
token
A valid reset token for this user
password
New password

Change password

POST /users/password/change

Change the password for the current authenticated user.

Parameters:

current
Current password
new
New password

Profile

GET /users/profiles/{username}

Return the following profile information for the current user, including all comments and ideas which have not been rejected by a moderator. Note that on discussions configured for pre-moderation this will include those items which are still awaiting moderation.

Returns

{
   "properties":{
      "country":"NI",
      "email":"alan@example.com"
   },
   "comments":[
      {
         "body":"I'm a comment\n",
         "state":"published",
         "created":"2014-02-13T12:34:00.324118",
         "id":"1392294840324132",
         "author":"AlanH"
      }
   ],
   "ideas":[
      {
         "average_rating":0.0,
         "ratings":0,
         "state":"new",
         "author":"AlanH",
         "title":"My tea-riffic idea",
         "discussion":"ideas",
         "tags":0,
         "id":"my-tea-riffic-idea",
         "comments":0,
         "created":"2014-02-19T15:53:06+00:00"
      }
   ]
}

Currently authenticated username

GET /users/authenticated

Return the username for the currently logged in user (based on the __ac cookie).

Example response:

"AlanH"

Discussions

Create discussion

POST /discussions

Create a new discussion.

Note: Creating private discussions is currently not supported.

Parameters:

title
Discussion title
summary
Short plain text summary for the discussion
body
Long description of the discussion. HTML is allowed but filtered

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"
   }
]

Get discussion

GET /discussions/{discussion_id}

Return all metadata for a specific discussion.

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

Example response:

{
   "body":"<p>Hey there's some information here</p>\r\n",
   "summary":"A discussion about sheeps",
   "id":"sheep",
   "title":"Sheep"
}

Ideas

Add idea

POST /discussions/{discussion_id}/ideas

Create a new idea in a specific discussion. HTML is permitted but may be filtered before output. Returns the generated idea ID.

Parameters:

title
Idea title
what
What is the idea
why
Why this idea is important

Example response:

"my-tea-riffic-idea-1"

Get idea

GET /discussions/{discussion_id}/ideas/{idea_id}

Return all information about a specific idea, this includes tags, comments (comments marked as rejected by a moderator are not included but those awaiting moderation are), average and number of ratings. Note that the what and why contain may contain (filtered) HTML.

Example response:

{
   "ratings":1,
   "state":"new",
   "tags":[

   ],
   "comments":[
      {
         "body":"I think this is an excellent idea",
         "state":"new",
         "created":"2014-02-19T16:04:51.129428",
         "id":"1392825891129442",
         "author":"admin"
      }
   ],
   "created":"2014-02-19T16:03:01+00:00",
   "title":"My tea-riffic idea",
   "author":"AlanH",
   "what":"What is this idea about",
   "average_rating":5.0,
   "why":"Why not?"
}

Add comment

POST /discussions/{discussion_id}/ideas/{idea_id}/comments

Add a comment to a specific idea.

Parameters:

body
Plain text comment body. Must not be blank.

Add rating

POST /discussions/{discussion_id}/ideas/{idea_id}/ratings

Set the current users rating for a specific idea. Users may not rate their own ideas

Note: To remove a rating, pass a blank value for rating.

Parameters:

rating
Rating value in string form, must be 1-5 or blank.

Add tags

POST /discussions/{discussion_id}/ideas/{idea_id}/tags

Add tags to a specific idea. Already applied tags are ignored.

Parameters:

tags
Comma separated list of the tags to apply to this idea.

Example response:

[
   "tea",
   "genius"
]

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
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"
   }
]

Search within specific discussion

POST /discussions/{discussion_id}/search

Identical behaviour to the default search, except restricts result to only ideas within a specific discussion. Return metadata (title, comment count, ratings etc) for all matching ideas in all discussions. Search terms are ANDed together.

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

Tag cloud

Tag cloud for all discussions

GET /tags

Return a mapping of all used tags to the number of ideas they were applied to

Example response:

{
   "cheese":6,
   "bar":1,
   "cheesey bees":6,
   "demo":1,
   "baz":1,
   "genius":1,
   "bees":7,
   "tea":1,
   "foo":1,
}

Tag cloud for specific discussion

GET /discussions/{discussion_id}/tags

Return a mapping of all used tags to the number of ideas they were applied to for a specific discussion.

Powered by Zendesk