This document details each of the web services available as part of the CWT product line. The Appendix provides detailed descriptions of the supporting databases.
All services are available only on behalf of logged-in members. The member ID is verified by looking up the site-specific authentication token in the loginCredentials table. As of this release, the login credential is presumed to be named CWTSESSID. Every call is expected to provide that identifier either as a session cookie or as part of the POST'ed parameter array. For simplicity, this is not repeated as part of each service's synopsis.
All services are accessed only through secure http, aka https, via URL's of the form:
All services are assumed to depend on the include files "cwt.inc" and/or "engine.inc" so these files are not repeated as part of each individual service's dependencies. The "cwt.inc" file also requires the database-specific information found in "$HOME/private/CWT_db.inc" (stored outside of the webroot for security); this is also not repeated below.
The "Parameters" section of each service's description lists parameters expected to be found in the POST data array. Note that querystring (i.e., GET) parameters are not used, for security reasons.
Notational conventions: items listed in [square brackets] are optional. Sets of alternatives are presented as a {comma-separated list inside curly braces}. Required parameters are listed in boldface.
| Change Log: | |
|---|---|
| 06-Jul-2014 | Initial release |
| 13-Jul-2014 | Updates for new scoring model, listQuestions, validity ranges |
| 21-Jul-2014 | Updates for organizational membership |
| 24-Jul-2014 | Added page for listTopAnswers service |
| 15-Oct-2014 | Revised listOrganizations, listQuestions for new org'l model |
| 10-Nov-2014 | Added pages for getAnswer, listMyAnswers services; updated all |
| 19-Nov-2014 | Added pages for getUserInfo, setFollow services |
| 08-Dec-2014 | Expanded setQuestion entry for admin actions; moved to Part II |
| 23-Apr-2015 | Extensive update for new/expanded services; reorganized and rewritten in MD |
The basic UI process loop:
1. Call listOrganizations to get all organizations to which this user belongs
A. User selects an organization
2. Call listScripts to get all scripts available for this user [for this org]
B. User selects a script in which to participate
3. Parse and process script:
3.1. Call getQuestion for details & set of existing answers
C. User answers the question
3.2. Call setAnswer to record the user's new answer
3.3. (If 'idea' question) Present existing answers to user for ranking
D. User ranks/checks answers
3.4. Call rateAnswers to record the new ratings
3.5. Evaluate user's answer and determine next script step
Where steps (1) and (A) are optional if a user chooses to see all available scripts and steps (C) and (3.2) are optional if a user chooses not to submit a new answer.
questionID=nnnnn // required
numAnswers=nnn // optional; defaults to DEFAULT_ANSWER_COUNT
This service returns a question ID, the text of the question, and an array of existing answers to that question (intended to provide for rating of the answers). The array of answers consists of two fields for each answer: the unique ID of the answer and its text.
{
"status": true,
"message": "Success with 2 answers returned.",
"requestID": "xxxxx",
"responseID": 999999,
"questionID": 88888,
"questionText": "text-of-question",
"type": "idea",
"setupURL": "http://foobar.com",
"minimum": 0,
"maximum": 9,
"answerCount": 2,
"answers": [
{
"answerID": "nnn",
"answerText": "yyy",
"answerDate": "yyyy-mm-dd hh:mm:ss"
},
{
"answerID": "nnn",
"answerText": "yyy",
"answerDate": "yyyy-mm-dd hh:mm:ss"
}
]
}
The user is required to be a member of the organization that owns the question, or a parent of that organization.
| Error Code | Conditions Under Which Returned |
|---|---|
| E_DBFAILURE | if database connection cannot be established |
| E_NOACCESS | if insufficient privilege |
| E_MISSINGDATA | if question ID not specified |
| E_INVALID | if specified question ID not found |