Appendix: Question Answer Formats

Essay Questions

• Question parametric type: essay_question
• Parameter type: Text
• Parameter synopsis: { "answer": "Answer text." }

Example request

{
  "answer": "<h2>My essay</h2>\n\n<p>This is a long article.</p>"
}

Possible errors

HTTP RC	Error Message	Cause
400 Bad Request	Text is too long.	The answer text is larger than the allowed limit of 16 kilobytes.

Fill In Multiple Blanks Questions

• Question parametric type: fill_in_multiple_blanks_question
• Parameter type: Hash{String => String}
• Parameter synopsis: { "answer": { "variable": "Answer string." } }

Example request

Given that the question accepts answers to two variables, color1 and color2:

{
  "answer": {
    "color1": "red",
    "color2": "green"
  }
}

Possible errors

HTTP RC	Error Message	Cause
400 Bad Request	Unknown variable 'var'.	The answer map contains a variable that is not accepted by the question.
400 Bad Request	Text is too long.	The answer text is larger than the allowed limit of 16 kilobytes.

Fill In The Blank Questions

• Question parametric type: short_answer_question
• Parameter type: String
• Parameter synopsis: { "answer": "Some sentence." }

Example request

{
  "answer": "Hello World!"
}

Possible errors

Similar to the errors produced by Essay Questions.

Formula Questions

• Question parametric type: calculated_question
• Parameter type: Decimal
• Parameter synopsis: { "answer": decimal } where decimal is either a rational number, or a literal version of it (String)

Example request

With an exponent:

{
  "answer": 2.3e-6
}

With a string for a number:

{
  "answer": "13.4"
}

Possible errors

HTTP RC	Error Message	Cause
400 Bad Request	Parameter must be a valid decimal.	The specified value could not be processed as a decimal.

Matching Questions

• Question parametric type: matching_question
• Parameter type: Array<Hash>
• Parameter synopsis: { "answer": [{ "answer_id": id, "match_id": id }] } where the IDs must identify answers and matches accepted by the question.

Example request

Given that the question accepts 3 answers with IDs [ 3, 6, 9 ] and 6 matches with IDs: [ 10, 11, 12, 13, 14, 15 ]:

{
  "answer": [{
    "answer_id": 6,
    "match_id": 10
  }, {
    "answer_id": 3,
    "match_id": 14
  }]
}

The above request:

• pairs answer#6 with match#10
• pairs answer#3 with match#14
• leaves answer#9 un-matched

Possible errors

HTTP RC	Error Message	Cause
400 Bad Request	Answer must be of type Array.	The match-pairings set you supplied is not an array.
400 Bad Request	Answer entry must be of type Hash, got '...'.	One of the entries of the match-pairings set is not a valid hash.
400 Bad Request	Missing parameter 'answer_id'.	One of the entries of the match-pairings does not specify an answer_id.
400 Bad Request	Missing parameter 'match_id'.	One of the entries of the match-pairings does not specify an match_id.
400 Bad Request	Parameter must be of type Integer.	One of the specified answer_id or match_id is not an integer.
400 Bad Request	Unknown answer '123'.	An answer_id you supplied does not identify a valid answer for that question.
400 Bad Request	Unknown match '123'.	A match_id you supplied does not identify a valid match for that question.

Multiple Choice Questions

• Question parametric type: multiple_choice_question
• Parameter type: Integer
• Parameter synopsis: { "answer": answer_id } where answer_id is an ID of one of the question's answers.

Example request

Given an answer with an ID of 5:

{
  "answer": 5
}

Possible errors

HTTP RC	Error Message	Cause
400 Bad Request	Parameter must be of type Integer.	The specified `answer_id` is not an integer.
400 Bad Request	Unknown answer '123'	The specified `answer_id` is not a valid answer.

Multiple Dropdowns Questions

• Question parametric type: multiple_dropdowns_question
• Parameter type: Hash{String => Integer}
• Parameter synopsis: { "answer": { "variable": answer_id } } where the keys are variables accepted by the question, and their values are IDs of answers provided by the question.

Example request

Given that the question accepts 3 answers to a variable named color with the ids [ 3, 6, 9 ]:

{
  "answer": {
    "color": 6
  }
}

Possible errors

HTTP RC	Error Message	Cause
400 Bad Request	Unknown variable 'var'.	The answer map you supplied contains a variable that is not accepted by the question.
400 Bad Request	Unknown answer '123'.	An answer_id you supplied does not identify a valid answer for that question.

Multiple Answers Questions

• Question parametric type: multiple_answers_question
• Parameter type: Array<Integer>
• Parameter synopsis: { "answer": [ answer_id ] } where the array items are IDs of answers accepted by the question.

Example request

Given that the question accepts 3 answers with the ids [ 3, 6, 9 ] and we want to select the answers 3 and 6:

{
  "answer": [ 3, 6 ]
}

Possible errors

HTTP RC	Error Message	Cause
400 Bad Request	Selection must be of type Array.	The selection set you supplied is not an array.
400 Bad Request	Parameter must be of type Integer.	One of the answer IDs you supplied is not a valid ID.
400 Bad Request	Unknown answer '123'.	An answer ID you supplied in the selection set does not identify a valid answer for that question.

Numerical Questions

• Question parametric type: numerical_question

This is similar to Formula Questions.

True/False Questions

• Question parametric type: true_false_question

The rest is similar to Multiple Choice questions.