Session REST API

Creating a new session

Request

To create a new answering session for a dialog, it needs to be POSTed to server, for example:

POST /api/questionnaires

{
  "metadata":
  {
    "formId": "2e3126acc2404726977963195c4d0082",
    "formRev": "LATEST",
    "language": "en",
    "submitUrl": "http://whatever.example.com/rest/api"
  },
  "context": [
  {
    "id": "contextVar1",
    "value": 21
  },
  {
    "id": "contextVar2",
    "value": "test"
  }]
}

• metadata
  • formId Mandatory identifier for dialog
  • formRev Dialog revision to point to specific version. use LATEST shorthand for choosing the newest version
  • language 2-letter language code to choose, defaults to English (en)
  • submitUrl Optional. If this is set, session state will be POSTed as JSON to this URL when session is completed.
  • Additional attributes with desired structure can be added to metadata and they are stored along with the session.
• context Optional. If dialog requires context variables to be set, list of those can be defined here.
  • id Context variable name
  • valueContext variable value

Note If dialog defines a context variable without default value, it is mandatory to use it when creating a session. If default value is set, context variable can be omitted from request.

Response

In case of successful creation of answering session, server responds with code 201 and following response:

{
  "_id":"88f3024ec3b1e0842e65c674e80138af",
  "_rev":"1-2374e9338682c26f3de47ec4df900578"
}

• _id Identifier for the newly created answering session. See here
• _rev Revision identifier for the session.

Requesting state of a session

Current state of an answering session can be requested by doing GET request to API, using session ID:

GET /api/questionnaires/149263bafc142790e53ec0dc35000596

Response

{
   "_id": "149263bafc142790e53ec0dc35000596",
   "_rev": "3-d87687e20665f7cb165eacc068a81c9d",
   "answers": [
       {
           "id": "group2[2].question5",
           "value": "f"
       },
       {
           "id": "group2[2].question4",
           "value": "e"
       },
       {
           "id": "group2[2].question3",
           "value": "d"
       },
       {
           "id": "group2[1].question5",
           "value": "c"
       },
       {
           "id": "group2[1].question4",
           "value": "b"
       },
       {
           "id": "group2[1].question3",
           "value": "a"
       },
       {
           "id": "question2",
           "value": [
               "a",
               "b"
           ]
       },
       {
           "id": "question1",
           "value": "answer text"
       }
   ],
   "tables": [
       {
           "tableId": "group2",
           "rows": [
               "group2[1]",
               "group2[2]"
           ]
       }
   ],
   "context": [
       {
           "id": "contextVar1",
           "value": "21"
       },
       {
           "id": "contextVar2",
           "value": "test"
       }
   ],
   "activeItem": "page1",
   "metadata": {
       "formId": "2e3126acc2404726977963195c4d0082",
       "formRev": "LATEST",
       "created": "2017-06-26T13:37:12.502+0000",
       "lastAnswer": "2017-06-26T13:37:32.956+0000",
       "label": "Submit test",
       "submitUrl": "http://whatever.example.com/rest/api",
       "status": "OPEN",
       "language": "en"
   }
}

• _id Session identifier
• _rev Revision identifier for the session
• activeItem an item ID pointing to currently active page
• metadata Session metadata
  • formId Mandatory identifier for dialog
  • formRev Dialog revision to point to specific version. use LATEST shorthand for choosing the newest version
  • language 2-letter language code to choose, defaults to English (en)
  • submitUrl Optional. If this is set, session state will be POSTed as JSON to this URL when session is completed.
  • created Timestamp when the session was created.
  • lastAnswer Timestamp when last answer was added.
  • status Current status of session:
    • OPEN Session is open, ready to receive answers.
    • COMPLETED Session is completed, will not receive any more answers.
  • Additional attributes that were added when creating the session will appear here.
• context Optional. If dialog requires context variables to be set, list of those can be defined here.
  • id Context variable name.
  • valueContext variable value.
• answers List of answers given by user:
  • id Question identifier
  • value Answer value
• tables Describes references to multi-row answer rows. List of following:
  • tableId Item id for multi-row group.
  • rows List of row identifiers, in that order. Row answer values are defined in answers section, with id combined as <rowId>.<itemId> (see to example above).

Complete REST API reference

Please refer to swagger documentation for latest API documentation.