REST API Documentation


Introduction

The Quandora REST API allows you to acces a Quandora domain using JSON based rest calls.

The REST API of a domain is available at https://your-domain.quandora.com/m/json where your-domain is your Quandora domain name. All the REST call definitions below will use absolute paths relative to this base URL.

Payload Format

The payload of a REST request or response is expressed as a JSON message which is structured as following:

{
  "type" : DATA-TYPE,
  "data" : DATA-VALUE
}

where DATA-TYPE is a JSON string defining the type of the nested message data and the DATA-VALUE is the actual message data that can be either a JSON primitive (i.e. null, string, boolean, int, object, array etc.) either a JSON array, either a JSON object. If the DATA-VALUE is an array then the DATA-TYPE define the type of the array components.

Primitive data types

  • string – a string value
  • boolean – a boolean value
  • integer – an integer value
  • long – a long value
  • float – a float value
  • double – a double value
  • date – a date in w3c format
  • void – no value is defined – usually the data field is null

String message

{
  "type": "string",
  "data": "the string value"
}

String array message

{
  "type": "string",
  "data": ["first string", "second string"]
}

Undefined string message

{
  "type": "string",
  "data": null
}

Complex data types

Usually, you need to send or receive complex messages (JSON objects) and not primitives. In the next section we will discuss about the complex object types defined by the Quandora REST API.

REST Objects

The Quandora REST API defines some custom object types exchanged by the client and the server in REST calls.

Note that in the REST call definitions we will use simplified notations like

{
  "type": "the_object_type",
  "data": ObjectType
}

or

{
  "type": "the_object_type",
  "data": [ ObjectType, ... ]
}

to describe JSON messages exchanged with the server.

The first example represent a single object of type “type” while the second example represent a list of objects of type “type”.

Message containing a single object may use a null value if the object is not defined, while messages containing list of objects will always use an empty array [] if the list is empty.

To get detailed information about the ObjectType value look into the corresponding section in this chapter.

Here is the complete list of Quandora REST objects:

EndPoint

An object describing a server end point. The type name is endpoint.

EndPoint Fields:

  • name – the end point name
  • method – the HTTP method to access the end point
  • url – the absolute path relative to Domain REST API base url
  • description – the end point description

Example

{
  "name" : "listBases",
  "method" : "GET",
  "url" : "/kb",
  "description" : "List the Knowledge bases available in this domain."
}

Error

An object describing a server exception. The type name is error.

Sent by the server in response to the client when an error occurs.

Error Fields:

  • code – an HTTP status code.
  • message – a message describing the error.
  • stackTrace – an optional stack trace as a string array. By default this is not filled by the server.

Example of an error object:

{
  "code" : 404,
  "message" : "Knowledge Base not found: mybase",
  "stackTrace" : [ ]
}

Example of an error message:

{
  "type" : "error",
  "data" : {
    "code" : 404,
    "message" : "Knowledge Base not found: mybase",
    "stackTrace" : [ ]
  }
}

Question

An object describing a question. The type name is question.

Returned by the server when fetching a question or as part of a query result.

Question Fields:

  • uid – the question UID.
  • baseId – the Knowledge Base UID.
  • title – the question title.
  • summary – the question summary. Note that this field is only included in question listings.
  • votes – the question votes count.
  • views – the question views count.
  • answers – the answers count.
  • created – the question creation date in w3c date format.
  • authorId – the UID of the author user profile object.
  • author – the question author as an UserProfile object.
  • tags – the question tags as an array of Tag objects.

Extra Question Fields:

  • content – the question content.
  • contentType – the question content type (either ‘markdown’ or ‘html’).
  • answersList – the answers list as an array of Answer objects.
  • comments – the question comments as an array of Comment objects.

Note

When listing questions or referencing a question from another object the extra fields are not included in the JSON object. These fields are included only when the full question information is request (i.e. when fetching a Question using GetQuestion or ViewQuestion methods).

Example

{
    "uid" : "81cab43e-95f3-4e88-b7a3-9cb9596c0d50",
    "title" : "My question",
    "votes" : 0,
    "views" : 5,
    "answers" : 1,
    "created" : "2012-11-17T10:36:08.97Z",
    "authorId" : "2e52a900-6256-434a-929f-9a822842ba66",
    "content" : "some content ...",
    "contentType" : "markdown",
    "answersList" : [ Answer, ... ],
    "comments" : [ Comment, ... ],
    "author" : UserProfile,
    "tags" : [ Tag, ... ],
    "baseId" : "79d72a5b-1c48-4f43-89a6-c12f1066e2f8"
  }

See UserProfile for the format of the “author” field, Comment for the “comments” list element format, Tag for the tag list element format and Answer for the answer list element format.

Answer

An object describing an answer. The type name is answer.

Returned by the server as part of a question object.

Answer Fields:

  • uid – the answer UID.
  • content – the answer content.
  • contentType – the answer content type (either ‘markdown’ or ‘html’).
  • comments – an array of Comment objects.
  • votes – the answer votes count.
  • accepted – a boolean value: true if this answer was accepted, false otherwise.
  • created – the answer creation date in w3c date format.
  • authorId – the UID of the author user profile object.
  • author – the answer author as an UserProfile object.

Example

{
    "uid" : "31199549-82c0-4743-934f-19871440dad3",
    "contentType" : "markdown",
    "content" : "my answer content",
    "comments" : [ Comment, ... ],
    "votes" : 0,
    "created" : "2012-10-18T10:44:16.52Z",
    "accepted" : false,
    "authorId" : "2e52a900-6256-434a-929f-9a822842ba66",
    "author" : UserProfile
}

See UserProfile for the format of the “author” field and Comment for the “comments” list element format.

UserProfile

An object describing an user profile. The type name is user.

Returned by the server as part of question / answer author objects or when listing users.

UserProfile Fields:

  • uid – the user UID.
  • name – the username – usually this is an alias for email.
  • email – the user email used as the username as well.
  • firstName – the user first name.
  • lastName – the user last name.
  • title – the user role in the company.
  • score – the user reputation score.
  • badgeCount – an array of 3 integers containing the count of the 3 different type of badges. On position 0 – bronze badge count, 1 – silver badge count, 2 – gold badge count.
  • gravatar – the user Gravatar key if any.

Extra UserProfile Fields:

  • notifications – a Notifications object describing the user notifications configuration.
  • badges – an array of badge names owned by the user.
  • loginCount – the user login count.
  • lastLogin – the timestamp of the last login.

Note

When listing user profiles or referencing an user profile from another object (like question / answer / comment) the extra fields are not included in the JSON object. These fields are included only when full user profile information is request (i.e. when fetching a Profile using GetUser REST method).

Example

{
  "uid" : "2e52a900-6256-434a-929f-9a822842ba66",
  "name" : "test@quandora.com",
  "email" : "test@quandora.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "title" : "Member",
  "score" : 50,
  "badgeCount" : [ 1, 0, 0 ],
  "gravatar" : "80baf82fd4d3d658e7316b4091c3e0e5"
}

Notifications

An object describing the user notifications configuration. The type name is notifications.

This object is included in the UserProfile object when fetching the full user profile definition.

Notifications Fields:

  • email – the email channel configuration – an object of type Channel described below.
  • phone – For future use.

Channel Fields:

  • name – the channel name.
  • address – the channel address (an email address in case of email channels)
  • notifs – a string array containing the notification IDs enabled on this channel.

Comment

An object describing an user comment. The type name is comment.

Returned by the server as part of question / answer objects.

Comment Fields:

  • author – the comment author as an UserProfile object.
  • text – the comment text.

Example

{
  "author" : UserProfile,
  "text" : " my comment"
}

See UserProfile for the author object format.

Tag

An object describing a tag. The type name is tag.

Returned by the server when listing tags or as part of question objects.

Tag Fields:

  • uid – the tag UID.
  • name – the tag name.
  • category – for future use.

Example

{
  "uid" : "3b46f72a-7873-4f55-8d92-98b297a1c860",
  "name" : "access-control",
  "category" : null
}

TagContent

An object describing the content and meta-data of a tag. The type name is tag-content.

Returned by the server when fetching complete tag information or posted by the client in order to create or update tags.

Tag Fields:

  • uid – the tag UID.
  • name – the tag name.
  • category – for future use.
  • location – optional tag ‘location’ meta-data
  • url – and optional url to be attached to a tag
  • author – read-only author field
  • lastModified – read-only last modified field in w3c date time format.

Example

{
  "uid" : "3b46f72a-7873-4f55-8d92-98b297a1c860",
  "name" : "javascript",
  "category" : null,
  "location": null,
  "url": "http://en.wikipedia.org/wiki/JavaScript",
  "content": "JavaScript (JS) is an interpreted computer programming language.",
  "author": "2e52a900-6256-434a-929f-9a822842ba66",
  "lastModified": "2012-10-18T10:44:16.52Z"
}

KBase

An object describing a Knowledge Base. The type name is kbase.

Returned by the server when listing Knowledge Bases.

KBase Fields:

  • objectId – the Knowledge Base UID.
  • objectName – the Knowledge Base name.
  • domain – the domain UID containing this Knowledge Base.
  • title – the Knowledge Base title.
  • description – the Knowledge Base description
  • anonymous – a boolean value: true if anonymous is allowed to browse this Knowledge base, false otherwise.
  • isRestricted – a boolean value: true if this base is a restricted to a group of users, false otherwise.

Example

{
  "objectId" : "79d72a5b-1c48-4f43-89a6-c12f1066e2f8",
  "objectName" : "quickstart",
  "domain" : "04d0e4ec-5db5-4b78-9684-614f975d27e5",
  "title" : "Quick Start",
  "description" : "",
  "anonymous" : false,
  "isRestricted" : false
}

Badge

An object describing a badge. The type name is badge.

Returned by the server when listing existent badges.

Badge Fields:

  • id – the badge id.
  • description – the badge description.
  • type – integer value describing the badge type. Possible values: 0 (bronze), 1 (silver), 2 (gold).

Example

{
  "id" : "critic",
  "description" : "Assigned to users that voted down at least 10 times",
  "type" : 0
}

QuestionSearchResult

An object describing a question search result. Provides pagination support. The type name is question-search-result.

This object is returned by the server as a response to a question query.

QuestionSearchResult Fields:

  • totalSize – the total count of the question that matched the query.
  • offset – the query offset as requested by the client (a 0 based index). Used for pagination.
  • limit – the query limit (maximum result size) as requested by the client. Used for pagination.
  • result – an array of Question objects. If nothing is found an empty array is returned.

Example

{
  "totalSize" : 26,
  "offset" : 0,
  "limit" : 15,
  "result" : [ Question, ... ]
}

See Question for the format of a result item.

MoreLikeThis

An object describing a more like this query result. The type name is mlt.

This object is returned by the server as a response to a more like this query.

MoreLikeThis Fields:

  • baseId – the UID of the Knowledge Base.
  • result – an array of Question objects. Maximum size is 10. If nothing is found an empty array is returned.

Example

{
  "baseId" : "e827595b-227a-4c94-ae7b-77f57e32651a",
  "result" : [ Question, ... ]
}

See Question for the format of a result item.

ActivityQueryResult

An object describing an activity query result. Provides pagination support The type name is activity.

ActivityQueryResult Fields:

  • offset – the query offset requested by the client (a 0 based index). Used for pagination.
  • limit – the query limit (maximum result size) requested by the client. Used for pagination.
  • result – an array of HTML activity logs. If no logs were found an empty array is returned.
{
  "offset" : 0,
  "limit" : 10,
  "result" : [ "activity log item as html string", ... ]
}

PostQuestion

An object describing a question post. The type name is post-question.

This object is posted by the client to create a new question.

PostQuestion Fields:

  • title – Required: the question title.
  • content – Optional: the question content.
  • contentType – Optional: the question content type. Possible values: ‘markdown’ or ‘html’. Default is ‘markdown’.
  • tags – Optional: An array of tag names to tag the question with. Not yet used.

Example

{
  "title" : "My question",
  "content" : "my **markdown** content",
  "contentType" : "markdown"
}

PostAnswer

An object describing an answer post. The type name is post-answer.

This object is posted by the client to create a new answer.

PostAnswer Fields:

  • content – Required: the answer content.
  • contentType – Optional: the answer content type. Possible values: ‘markdown’ or ‘html’. Default is ‘markdown’.

Example

{
  "content" : "my **markdown** answer",
  "contentType" : "markdown"
}

PostComment

An object describing a comment post (comments can be posted on both questions or answers). The type name is post-comment.

This object is posted by the client to create a new comment. In order to update an existing comment you must PUT this object and provide the hash parameter.

PostComment Fields:

  • content – Required: the comment content in markdown format.
  • hash – Required only when updating a comment. Not used when posting a new comment.

Example

Creation:

{
  "content" : "my **markdown** comment",
}

Update:

{
  "content" : "my updated **markdown** comment",
  "hash" : "e7cabc9687f40186fc947829f1bcb316"
}

PostUser

An object describing an user to post. The type name is post-user. This object is posted by the client to create new Quandora user profiles. To be able to use Quandora stored users you need to activate Quandora login in the Access Policy management page.

PostUser fields:

  • email – Required: the user main e-mail which will be used as the user identifier.
  • password – Optional: the user password. If no password is set the user will not be able to log-in. But you can still post content in his name using RunAs Operations
  • lastName – Optional: the user last name.
  • firstName – Optional: the user first name
  • title – Optional: the user title
  • aliases – Optional: an array of extra user e-mails.
  • groups – Optional: an array of user groups
  • isManager – a boolean indicating if the user is a manager or not.

The post-user object must define at least the email field. If you are not interested in setting a specific field just ignore it.

Example

{
  "type" : "post-user",
  "data" : {
    "email": "jdoe@quandora.com",
    "password": "xxx",
    "firstName" : "John",
    "lastName" : "Doe",
    "title" : "developer",
    "isManager": false,
    "aliases": ["bogdan+rest+alias@quandora.com"],
    "groups": ["admin","@adminitsrators"]
  }
}

Authentication

Depending on the domain settings you want to access (i.e. if the domain doesn’t allows anonymous read access) you must login before executing a REST call. You have two methods to login:

  1. Using HTTP Basic Authentication.
  2. Using external login – either through Google Apps, Salesforce, Yammer or Quandora login form.

If the domain allows anonymous access – you will have read only access through the REST API without needing to login. If you login using one of the methods above, the REST API will be restricted to sections you can access using your credentials.

HTTP Basic Authentication

To use Basic Authentication you need to setup a password for your Quandora account you want to use to connect through the REST API. Even if your account is a Google account you can set a password from the Profile Preferences page.

To use HTTP basic authentication simply add a Basic Authentication header to your rest calls:

Example

curl --user email:password https://your_domain.quandora.com/m/json

RunAs Operations

Sometimes you need to execute all operations using an unique REST user (e.g. a robot user with manager rights) that acts in the name of other (real) users in the system. This can be done using RunAs calls as explained bellow.

In order to perform REST API calls in the name of an other user: – the call must login with a manager account. (non manager accounts cannot be used in conjunction with RunAs) – the call must set a custom header: X-Quandora-RunAs which points to the email of the real user to run as.

Example:

curl -v --user "foo@quandora.com:xxx" -H "X-Quandora-RunAs: bar@quandora.com" "https://test.quandora.com/m/json/users/me"

will display the information about the user bar@quandora.com, while the following call:

curl -v --user "bogdan@quandora.com:xxx" "https://test.quandora.com/m/json/users/me"

will display the information about the user foo@quandora.com

Note that if the authentication fails, a 401 status code will be returned.

When doing a RunAs operation – if the manager authentication succeeds but the RunAs user email cannot be found in Quandora (the user doesn’t exists) then a 412 status code will be returned. You can use this code to create users on the fly …

Example (PSEUDO CODE):

request = performRunAsRequest(url, runAs)
if (request.status < 400) {
  // Request OK - get the content returned by the server
} else if (request.status == 412) { // RunAs user doesn't exists
   createUser(runAsUserInfo);
   request = performRunAsRequest(url, runAs)
} else {
  throw Error
}

Domain API

ListEndpoints (GET /)

List the endpoints available on the domain.

Request

curl --user email:password https://your_domain.quandora.com/m/json

Response

{
  "type" : "endpoint",
  "data" : [ EndPoint, ... ]
}

See EndPoint object for the format of an element in the "data" list.

ListBases (GET /kb)

Lists the Knowledge Bases in this domain. Pagination is not supported.

Request

curl --user email:password https://your_domain.quandora.com/m/json/kb

Response

{
  "type" : "kbase",
  "data" : [ KBase, ...]
}

See KBase object for the format of an element in the "data" list.

ListBadges (GET /badges)

Lists the badges definition. Pagination is not supported.

Request

curl --user email:password https://your_domain.quandora.com/m/json/badges

Response Example:

{
  "type" : "badge",
  "data" : [ Badge , ... ]
}

See Badge object for the format of an element in the "data" list.

ListUsers (GET /users)

Lists the user profiles in this domain.

Parameters

  • o - Optional: an offset for pagination. The default is 0.
  • l - Optional: a limit for pagination (maximum number of returned users). Default is 15.

Request

curl --user email:password https://your_domain.quandora.com/m/json/users
curl --user email:password https://your_domain.quandora.com/m/json/users?l=100
curl --user email:password https://your_domain.quandora.com/m/json/users?l=100&o=200

Response

{
  "type" : "user",
  "data" : [ UserProfile, ... ]
}

See UserProfile object for the format of an element in the "data" list.

GetActivity (GET /activity)

Get the activity logs for the given domain. If the userId parameter is specified then will only returns the activity of that user inside the domain.

The logs are returned as an array of HTML items.

Parameters

  • userId - Optional: specify an user UID as a filter for the activity logs
  • o - Optional: an offset for pagination. The default is 0.
  • l - Optional: a limit for pagination (maximum number of returned log items). Default is 50.

Request Examples:

curl --user email:password https://your_domain.quandora.com/m/json/activity
curl --user email:password https://your_domain.quandora.com/m/json/activity?o=100&l=50
curl --user email:password https://your_domain.quandora.com/m/json/activity?o=100&l=50&userId=2e52a900-6256-434a-929f-9a822842ba66

Response

{
  "type" : "activity",
  "data" : ActivityQueryResult
}

See ActivityQueryResult for the format of the data field.

Knowledge Base API

Knowledge bases are identified using their UID or their name. All knowledge base API paths starts with /kb/:baseId where baseId is either the base UID either the base name.

ListQuestions (GET /kb/:baseId/list)

List questions in the given kbase.

Paramaters

  • q - Optional: the query to use when searching questions. If not specified all questions are returned.
  • o - Optional: the offset to use when limiting results - used for pagination. The default offset is 0.
  • l - Optional: the maximum number of questions to return - used for pagination. The default limit is 15.
  • tag - Optional: if specified returns only questions tagged using that tag. If not specified no tag filtering is done.
  • s - Optional: a sort method. Possible values are: 'newest', 'active', 'popular'. The default is 'newest'.

Request Examples

curl --user email:password "https://your_domain.quandora.com/m/json/kb/:kbaseId/list"
curl --user email:password "https://your_domain.quandora.com/m/json/kb/:kbaseId/list?o=100&l=50"
curl --user email:password "https://your_domain.quandora.com/m/json/kb/:kbaseId/list?q=some+text"
curl --user email:password "https://your_domain.quandora.com/m/json/kb/:kbaseId/list?q=some+text&tag=java"

Response

{
  "type" : "question-search-result",
  "data" : QuestionSearchResult
  }
}

See QuestionSearchResult for the format of the data field.

MoreLikeThisQuery (GET /kb/:baseId/mlt)

Perform a "more like this" query on a text and return maximum 10 of the most related questions.

Parameters

  • q - Required: the text to match.

Request Example

curl --user email:password "https://your_domain.quandora.com/m/json/kb/:kbaseId/mlt?q=some+text"

Response Example

{
  "type" : "mlt",
  "data" : MoreLikeThis
}

See MoreLikeThis for the format of the data field.

Ask (POST /kb/:baseId/ask)

Post a new question inside the given Knowledge base.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/kb/:kbaseId/ask"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "post-question",
  "data" : {
    "title" : "My Question",
    "content" : "my **markdown* question",
    "contentType" : "markdown"
  }
}

See PostQuestion for more details on the JSON 'data' field format.

The server will return a response of type string with the 'data' field pointing to the UID of the created question.

Response

{
  "type" : "string",
  "data" : "5c298a6d-875e-40cc-85ee-6ee8d3f3d0ba"
}

FollowBase (POST /kb/:baseId/follow)

Follow the given Knowledge Base.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/kb/:kbaseId/follow"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "boolean",
  "data" : true
}

The 'data' field can be either set to true - to follow the Knowledge Base, either to false - to unfollow the Knowledge Base.

The server will return a response of type boolean with 'data' = true if the Knowledge Base is followed or false otherwise.

Response

{
  "type" : "boolean",
  "data" : true
}

Question API

Questions are identified using the question UID in the request path. All question API paths starts with /q/:questionId where questionId is the question UID.

GetQuestion (GET /q/:questionId)

Fetch a question metadata and content given its UID.

Request

curl --user email:password https://your_domain.quandora.com/m/json/q/:questionId

Response

{
  "type" : "question",
  "data" : Question
}

See Question object for the format of the 'data' field.

ViewQuestion (GET /q/:questionId/view)

Same as GetQuestion but increment the question views counter. (as if the question was visited by an user)

MoreLikeThis (GET /q/:questionId/mlt)

Perform a "more like this" query on the given question and return maximum 10 of the most related questions.

Request Example

curl --user email:password "https://your_domain.quandora.com/m/json/q/:questionId/mlt"

Response Example

{
  "type" : "mlt",
  "data" : MoreLikeThis
}

See MoreLikeThis for the format of the data field.

Answer (POST /q/:questionId/answer)

Post an answer to the given question.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/q/:questionId/answer"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "post-answer",
  "data" : {
    "content": "my **markdown** answer",
    "contentType": "markdown"
  }
}

See PostAnswer for more information on the format of the 'data' field.

The server will return a response of type String with the 'data' field pointing to the UID of the created answer.

Response

{
  "type" : "string",
  "data" : "425df652-9c08-4a29-b57f-4c077e7dccd2"
}

VoteQuestion (POST /q/:questionId/vote)

Vote up or down the given question.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/q/:questionId/vote"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "boolean",
  "data" : true
}

The 'data' field can be either set to true - to vote up or false to vote down.

The server will return a response of type long with the 'data' field pointing to the question score.

Response

{
  "type" : "long",
  "data" : 1
}

Be aware that you cannot vote your own question. If you do so the server will return an error message like this:

{
  "type" : "error",
  "data" : {
    "code" : 200,
    "message" : "You cannot vote your own question",
    "stackTrace" : [ ]
  }
}

CreateQuestionComment (POST /q/:questionId/comment)

Post a comment on a question.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/q/:questionId/comment"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "post-comment",
  "data": {
    "content": "my rest comment"
  }
}

The server will return a response of type string with the 'data' field pointing to the comment hash. The hash is needed to remove or update comments.

Response

{
  "type" : "string",
  "data" : "e7cabc9687f40186fc947829f1bcb316"
}

UpdateQuestionComment (PUT /q/:questionId/comment)

Update an existing question comment. The comment to update is identified using its hash.

Request

curl --user email:password -X PUT -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/q/:questionId/comment"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "post-comment",
  "data": {
    "content": "my rest comment",
    "hash": "d2b7002afc0a3e6a0c3bcd2b24014696"
  }
}

The hash is the comment hash you can retrieve by fetching a question (or answer) content. The hash is used to identify the comment. The server will return a response of type string with the 'data' field pointing to the new comment hash. The hash change each time you modify a comment.

Response

{
  "type" : "string",
  "data" : "e7cabc9687f40186fc947829f1bcb316"
}

RemoveQuestionComment (DELETE /q/:questionId/comment/:hash)

Remove an existing question comment. The comment to remove is identified using its hash.

Request

curl --user email:password -X DELETE "https://your_domain.quandora.com/m/json/q/:questionId/comment/:hash"

Response

The server will respond 200 on success.

Answer API

Answers are identified using the answer UID in the request path. All answer API paths starts with /a/:answerId where answerId is the answer UID.

VoteAnswer (POST /a/:answerId/vote)

Vote up or down an answer.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/a/:answerId/vote"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "boolean",
  "data" : true
}

The 'data' field can be either set to true - to vote up or false to vote down.

The server will return a response of type long with the 'data' field pointing to the answer score.

Response

{
  "type" : "long",
  "data" : 2
}

Be aware that you cannot vote your own answer. If you do so the server will return an error message like this:

{
  "type" : "error",
  "data" : {
    "code" : 200,
    "message" : "You cannot vote your own answer",
    "stackTrace" : [ ]
  }
}

AcceptAnswer (POST /a/:answerId/accept)

Accept an answer.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" "https://your_domain.quandora.com/m/json/a/:answerId/accept"

where post message is a string containing the POST message below:

POST Message

{
  "type" : "boolean",
  "data" : true
}

The 'data' field can be only set to true - to accept the answer. "Un-accepting" answers is not yet supported.

The server will return a response of type boolean with the 'data' = true if the answer is accepted, false otherwise.

Response

{
  "type" : "boolean",
  "data" : true
}

Be aware that you cannot accept answers if the question does not belong to you. If you do so the server will return an error message like this:

{
  "type" : "error",
  "data" : {
    "code" : 200,
    "message" : "You are not the question author - you cannot accept an answer",
    "stackTrace" : [ ]
  }
}

CreateAnswerComment (POST /a/:answerId/comment)

Post a comment on an answer.

This operation is identical to CreateQuestionComment.

UpdateAnswerComment (PUT /a/:answerId/comment)

Update an answer comment.

This operation is identical to UpdateQuestionComment.

RemoveAnswerComment (DELETE /a/:answerId/comment/:hash)

Remove an action comment.

This operation is identical to RemoveQuestionComment.

Tag API

Tags are light objects that can be attached to a question (to tag the question). The tag name is must have an unique name made of alphanumeric characters + some common characters like _ # + etc. (spaces are not allowed) A tag can hold several metadata like a location, an url, a category and some HTML content. Tags are stored at Knowledge Base level.

There are 2 category of tag end points: * one for managing and listing tags. These end points are available under: /kb/:baseId/tags * one for managing tagged questions (add / delete tag on a given question). These end points are available under: /q/:questionId/tags

ListTags (GET /kb/:baseId/tags)

Query Knowledge Base tags. If no category or query term is specified all tags are returned.

Paramaters

  • c - Optional: the tag category
  • q - Optional: the term query. For example: 'java' will match tags as java, javascript, java_se etc.
  • o - Optional: pagination offset. The default is 0
  • l - Optional: pagination limit (i.e. the maximum number of entries to return). The default limit is 50.

Request

curl --user email:password https://your_domain.quandora.com/m/json/kb/:baseId/tags

Response

{
  "type" : "tag",
  "data" :  [ Tag, ... ]
}

See Tag object for the format of the 'data' field.

GetTag (GET /kb/:baseId/tags/:tagName)

Get complete information about a tag given its name.

Request

curl --user email:password https://your_domain.quandora.com/m/json/kb/:baseId/tags/:tagName

Response

{
  "type" : "tag-content",
  "data" :  TagContent
}

See TagContent object for the format of the 'data' field.

If the tag identified by :tagName doesn't exists an HTTP 404 error is returned as following:

{
  "type" : "error",
  "data" : {
    "code" : 404,
    "message" : "No such tag javascript",
    "stackTrace" : [ ]
  }
}

GetTaggedQuestions (GET /kb/:baseId/tags/:tagName/questions)

List all questions tagged with the given tag name.

Paramaters

  • s - Optional: the sort method to use. Default is 'newest'. Allowed values are: 'newest', 'active', 'popular'
  • o - Optional: pagination offset. The default is 0
  • l - Optional: pagination limit (i.e. the maximum number of entries to return). The default limit is 15.

Request

curl --user email:password https://your_domain.quandora.com/m/json/kb/:baseId/tags/:tagName/questions

Response

{
  "type" : "question-search-result",
  "data" :  QuestionSearchResult
}

See QuestionSearchResult object for the format of the 'data' field.

CreateTag (POST /kb/:baseId/tags)

Create a new tag given a TagContent JSON object. The TagContent object must define at least the name property.

Request

curl --user email:password -X POST -H "Content-Type: application/json" -d "post message" https://your_domain.quandora.com/m/json/kb/:baseId/tags

where post message is a message containing a TagContent object. Example:

{
  "type":"tag-content",
  "data": {
    "name": "javascript",
    "category": null,
    "location": null,
    "url": "http://en.wikipedia.org/wiki/JavaScript",
    "content: "some html content"
  }
}

See TagContent object for the format of the 'tag-content' object.

Response

{
  "type" : "string",
  "data" : "c07ab64a-62b5-430f-bef7-6294ab9967ec"
}

where the returned data represent the newly created tag UID. If the tag already exists an HTTP 409 status code is returned as following:

{
  "type" : "error",
  "data" : {
    "code" : 409,
    "message" : "Tag already exists: javascript",
    "stackTrace" : [ ]
  }
}

UpdateTag (PUT /kb/:baseId/tags)

Update an existing tag given a TagContent JSON object. The TagContent must define at least the uid property. This end point works in same manner as the previous one (i.e. CreateTag) but you must use a PUT instead of a POST.

Note that for now you cannot rename a tag (i.e. changing the name property will do nothing).

Request

curl --user email:password -X PUT -H "Content-Type: application/json" -d "post message" https://your_domain.quandora.com/m/json/kb/:baseId/tags

where post message is a message containing a TagContent object. Example:

{
  "type":"tag-content",
  "data": {
    "uid": "c07ab64a-62b5-430f-bef7-6294ab9967ec",
    "content: "some modified html content"
  }
}

See TagContent object for the format of the 'tag-content' object.

Response

{
  "type" : "string",
  "data" : "c07ab64a-62b5-430f-bef7-6294ab9967ec"
}

where the returned data represent the tag UID. If the tag identified by the given UID doesn't exists an HTTP 404 status code is returned as following:

{
  "type" : "error",
  "data" : {
    "code" : 404,
    "message" : "No such tag: c07ab64a-62b5-430f-bef7-6294ab9967ec",
    "stackTrace" : [ ]
  }
}

DeleteTag (DELETE /kb/:baseId/tags/:tagName)

Delete an existing tag

Request

curl --user email:password -X DELETE https://your_domain.quandora.com/m/json/kb/:baseId/tags/:tagName

Warning - use this method with care since the Knowledge base may contains questions tagged with the tag you want to remove.

Response

{
  "type" : "boolean",
  "data" : true
}

If the tag doesn't exists a 404 HTTP error will be returned:

{
  "type" : "error",
  "data" : {
    "code" : 404,
    "message" : "No such tag javascript",
    "stackTrace" : [ ]
  }
}

ListQuestionTags (GET /q/:questionId/tags)

Lis all tags on the question identified by :questionId

Request

curl --user email:password https://your_domain.quandora.com/m/json/q/:questionId/tags

Response

{
  "type" : "tag",
  "data" :  [ Tag, ... ]
}

See Tag object for the format of the 'data' field.

SetQuestionTags (POST /q/:questionId/tags/:tagNames)

Replace all tags on the given question with the tags specified as a comma separated list of tag names (:tagNames)

Important: The tag names are used to resolve actual tag objects from the repository. If a tag object doesn't exists for a given tag name then it will be created and then used to tag the question. If the tag already exists then it will be used to tag the question.

Request

curl --user email:password -H "Content-Type: application/json" -H "Content-Length: 0" -X POST https://your_domain.quandora.com/m/json/q/:questionId/tags/java,javascript

This will remove any tags on the :questionId then will tag the question with java and javascript tags.

You can specify a single tag as following:

curl --user email:password -H "Content-Type: application/json" -H "Content-Length: 0" -X POST https://your_domain.quandora.com/m/json/q/:questionId/tags/java

Note since this method doesn't post any content you must specify a "Content-Length: 0" header.

Response

{
  "type" : "boolean",
  "data" :  true
}

The data value is true if the tags were modified, or false if no modification were required.

If you use try to set invalid tag names a validation error will be returned:

curl --user email:password -H "Content-Type: application/json" -H "Content-Length: 0" -X POST https://your_domain.quandora.com/m/json/q/:questionId/tags/ja*va

{
  "type" : "error",
  "data" : {
    "code" : 400,
    "message" : "Invalid tag names: Invalid tag: ja*va",
    "stackTrace" : [ ]
  }
}

AddQuestionTags (PUT /q/:questionId/tags/:tagNames)

This operations has the same syntax as the operation above (i.e. SetQuestionTags) but you must use the PUT method. The difference is that the specified tags are added on the questions (i.e. the existing tags are not removed)

curl --user email:password -H "Content-Type: application/json" -H "Content-Length: 0" -X PUT https://your_domain.quandora.com/m/json/q/:questionId/tags/java,javascript

DeleteQuestionTags (DELETE /q/:questionId/tags/:tagNames)

Remove the specified tags from the given question

The :tagNames is a comma separated list of tag names. Example: java,javascript

Request

curl --user email:password -X DELETE https://your_domain.quandora.com/m/json/q/:questionId/tags/java,javascript

You can also remove a single tag as following:

curl --user email:password -X DELETE https://your_domain.quandora.com/m/json/q/:questionId/tags/java

Response:

{
  "type" : "boolean",
  "data" : true
}

The data value is true if the tag were changed (the specified tags were on the question and were removed) or false if no changes were done because the given tags were not set on the question.

User Profile API

User Profiles are identified using the user UID in the request path. All user profile API paths starts with /users/:userId where userId is the user UID.

GetUser (GET /users/:userId)

Get the user profile given its UID.

Request

curl --user email:password https://your_domain.quandora.com/m/json/users/:userId

Response

{
  "type" : "user",
  "data" : UserProfile
}

See UserProfile object for the format of the 'data' field.

GetCurrentUser (GET /users/me)

This is a shortcut to get the currently authenticated user.

Example:

curl --user email:password https://your_domain.quandora.com/m/json/users/me

CreateUser (POST /users)

Create a new user. The caller must be have manager rights.

Example:

curl -v --user "email:password" -X POST -H "Content-Type: application/json" -d "create user" "https://your-domain.quandora.com/m/json/users"

where create user is a string containing the post-user object below:

{
  "type" : "post-user",
  "data" : {
    "email": "bogdan+rest@quandora.com",
    "password": "xxx",
    "firstName" : "Dev",
    "lastName" : "User",
    "title" : "developer",
    "isManager": false,
    "aliases": ["bogdan+rest+alias@quandora.com"],
    "groups": ["admin","@adminitsrators"]
  }
}

See PostUser for more information on the format of the 'data' field.

If successful you will get back the user Unique ID:

{
  "type" : "string",
  "data" : "71edae9f-fd15-4ce7-ac79-25c3c1619f8c"
}

Reporting API

There are 3 end points that can be used for generating reports on Knowledge base usage.

QuestionAsked (GET /kb/:baseId/report/asked)

  • Input: Start Date and End Date
  • Output: a list of all questions asked on that KB during that date range, including question title, question body, and question author's name.

Paramaters

  • from - Optional: the start date in W3C date time format (ISO 8601). Default is one moth ago.
  • to - Optional: the end date in W3C date time format. Default is now.
  • o - Optional: pagination offset. The default is 0
  • l - Optional: pagination limit (i.e. the maximum number of entries to return). The default limit is 100.

UsersByReputationChange (GET /kb/:baseId/report/usersByReputationChange)

  • Input: Start Date and End Date
  • Output: A list of all users of that KB, including their name and their total reputation change during that date range.

Paramaters

  • from - Optional: the start date in W3C date time format (ISO 8601). Default is one moth ago.
  • to - Optional: the end date in W3C date time format. Default is now.
  • o - Optional: pagination offset. The default is 0
  • l - Optional: pagination limit (i.e. the maximum number of entries to return). The default limit is 100.

MostVotedQuestion (GET /kb/:baseId/report/mostVotedQuestion)

  • Input: Start Date and End Date
  • Output: The single question and single answer, including content and author name, that were voted up the most during that date range.

Paramaters

  • from - Optional: the start date in W3C date time format (ISO 8601). Default is one moth ago.
  • to - Optional: the end date in W3C date time format. Default is now.
  • l - Optional: pagination limit (i.e. the maximum number of entries to return). The default limit is 1.
×