Introduction¶
In the standard setup, dotData the respondent gets directed into a questionnaire, after which dotData generates HTML to be displayed in the respondents browser. This HTML contains a form that the respondent can post, after which he receives the next question.
This section describes an alternative method: a JSON API. Using this API you can build your own app that interacts with the questionnaire engine. The advantage of this is that you have full control over rendering of the pages. The API just delivers the logical structure of the items (e.g. question text and answer categories), after which it is your app’s responsibility to facilitate interaction with the respondent. This includes validation of the answers and posting of the result back to the server.
Note
We’ve built for this purpose an HTML example that simulates the behavior of an app. This example can be found here: (todo: insert link)
Respondent session lifecycle¶
The respondent lifecycle has the following phases:
initiation: the app creates a URL that is used to initiate the session. This requires that the app has a URL available that indicates which questionnaire should be targeted.
the app receives an initial JSON object. This object contains the elements of the instruction text, question or questions on the first page.
the app renders the item.
the respondent interacts with the app to answer the question or to finish the task
the app peforms a POST to the server with the given answer
the server feeds the next screen of questions
The JSON object will contain question-related elements and control-elements. Control-elements are elements that need to be posted back to the server in order to guarantee safetey and consistency of the session. These elements are:
- sessionid¶
this is a regular session id assigned by the server
- questions¶
this is a list of question id’s that are posted. From the perspective of dotData could happen that a respondent operates both in a browser and in your app, or also on a desktop machine. Because of that, we need to verify what exact page is being posted. This list is comma delimited and the posted value should be the same as the received value
- respid¶
the unique id of this participation. This is not the same as a session id. A session id might expire, but the id of this participation is fixed in time
- IID¶
the internal number of the questionnaire
- R4A¶
a checksum that is provided by the server. This checksum is a sum of all the above elements, hashed by the server. We use this key to ensure that none of the other values have been tweaked with
- R4ACSRF¶
usually this field is used in browser sessions, it provides a mechanism for us to set a secure cookie and match that up with the posted form element to guarantee that the post is actually coming from the same source as where we sent the form to, see https://en.wikipedia.org/wiki/Cross-site_request_forgery
Elements in a JSON item¶
The following structure of the JSON items apply. Note that some of the elements do or do not have relevance for certain question types. For instance, an instruction text has no answerable elements, hence there are no ‘answer categories’.
- item text¶
The text of the item, either an instruction text or the question
- varlabel¶
The label of the item that serves as a base for the POST variables. For instance, an item labeled ‘AGE’ should be posted as ‘AGE’.
- panswers¶
These are the answer categories (‘male, female’)
- subjects¶
These are subjects and can be conceptually seen as sub-questions (do you use the following products: ‘ipad, phone, desktop, none’)
A subject can be mutually exclusive to other subjects (‘none’)
- contexts¶
These are sub-questions of sub-questions (on which days do you use ‘ipad, phone, desktop’: ‘monday tuesday, wednesday’)
- validation¶
This is typically a regular expression