Qwizcards API

 

Note: URLs are https://qwizcards.net/admin/<script name>

Parameters may be specified as either POST or GET variables

Register new user

script name: new_student_registration
POST or GET variables Definition Value examples/alternatives Required?
(default)
login_f Existing user [null] Required
school_id ID indicating independent student 1 Required
username Login name bmontgomery [must be unique] Required
password Password 32xyzzy! Required
firstname First name Bob Optional
lastname Last name Montgomery Optional
email Email address bmontgomery2004@gmail.com Optional

Response.  The only relevant variable (json-formatted) is:

errmsg: [null] = OK; non-null = error message

Login

script name: login
POST or GET variables Definition Value examples/alternatives Required?
(default)
username Login name kendra Required
password Password 23scrxyz! Required
return Whether success/failure data should be returned in json format json Optional (default: JavaScript callback)

Response.  If return=json set, this array of variables is returned:

login_ok: <0 or 1>
session_id: <authorization ID>
app_free_user: <0 or 1; whether user can access all topics>
bundled_license_app_user: <0 or 1; whether user, as a class member, can access all topics under a bundled license>
class_confirmation_required_by: <(optional) date (yyyy-mm-dd) by which teacher must confirm class membership for continued access to app>

Delete user account

script name: delete_taker_account
POST or GET variables Definition Value examples/alternatives Required?
(default)
session_id Login session ID 424196734 Required

Response (json-formatted):

errmsg: “ok” or error message

Retrieve questions from a dataset

script name: get_dataset_questions_v2
POST or GET variables Definition Value examples/alternatives Required?
(default)
dataset Dataset name AP_Bio_phone_App_DS Required
page_url URL of page presenting (“using”) dataset https://www.sciencemusicvideos.com/benwokenfeld Required
qname Quiz/deck specifier qwiz_
qcard_		 Required
i_qwiz_qdeck Which quiz or deck on page (quizzes/decks numbered separately) 0
1
…		 Required
n_questions_in_set Maximum number of questions/cards to return 20
10000		 Required
qwiz_session_id Session ID for logged-in user 996971646 Optional (default: user not logged in, cannot indicate “questions already answered”, etc)
qrecord_id ID of quiz/deck for recording user responses dank-qwiz-conceptual-chemistry Optional (default: responses not recorded)
units Base 64-encoded JSON string of array of unit names — return questions/cards with these unit names chemistry Optional (default: any questions/cards returned)
topics Base 64-encoded JSON string of array of topic names (subcategory of units) — return questions/cards with these topic names organic
inorganic		 Optional (default: any questions/cards within specified units returned)
questions_to_do Which questions/cards returned (only when responses recorded) spaced_repetition
all
new (user hasn’t previously attempted)
incorrect		 Optional (default: spaced_repetition)
random_f Whether questions/cards returned in random order 1 Optional (default: false – questions/cards in order as entered in dataset source)
json Whether JSON structure returned instead of HTML 1 Optional (default: HTML for each question returned)

Response: Either (1) questions/cards HTML (separated by “[qQq]”) or (2) questions/cards json structure

Store quiz response to database

script name: record_response
POST or GET variables Definition Value examples/alternatives Required?
(default)
qname Quiz/deck specifier qwiz_ Required
i_qwiz Which quiz on page 0
1		 Required
qwiz_session_id User login session ID 996971646 Required, must be non-expired
qrecord_id ID of quiz/deck for recording user responses dan_k-functional-groups-1 Required
qrecord__id_ok Check qrecord_id If set, check whether user is enrolled in class that has assigned (will give credit for) this quiz Optional (default: qrecord_id not checked)
type Type of question start [should be sent when user begins using a quiz after a page load/reload]
multiple_choice
hangman
textentry [free-form input]
labeled_diagram
hotspot diagram
q_and_a_text Question and answer text What question is being recorded? Required, unless
type=start
i_question Number of question Which question in quiz (non-datasets).  For dataset questions, use the question’s dataset_id (that looks like multiple-choice-quiz|2194cccaa6f394) Required, unless
type=start
unit Unit (category) name Which category in quiz? Optional (default: none)
response Response that user chose or entered Text of multiple-choice answer chosen, or free-format word selected, or text of labeled-diagram label (when dropping onto target), or “done” (when labeled diagram completed), or text of the hotspot clicked label<tab>text of hotspot correct label (when click hotspot diagram), or “done” (when hotspot diagram completed) Required, unless
type=start
correct_b Correct response entered Flag whether user answer correct “1” or not “” (that is, use null response for incorrect answer) Required, unless
type=start
confirm Whether JSON structure returned json Optional (default: no response data)
app_version Which version of app used 2020_In_App_Purchase Optional (default: none)

Response
(when confirm=json): Array indexed by these variable names: qrecord_id, dataset_id, errmsg, ok (value 1 or 0)

Store elapsed time for quiz to database

script name: record_quiz_time
POST or GET variables Definition Value examples/alternatives Required?
(default)
qname Quiz/deck specifier qwiz_ Required
i_qwiz Which quiz on page 0
1		 Required
qwiz_session_id User login session ID 996971646 Required, must be non-expired
qrecord_id ID of quiz dan_k-functional-groups-1 Required
elapsed_time Time (integer seconds) to complete quiz 25 Required
Response
Array indexed by these variable names:
quiz_elapsed_time_id 432 (integer ID used to update user initials — see update_quiz_elapsed_time)
when_done_unix Unix timestamp – when current user did quiz  (used to match element of array “dates” returned by get_quiz_times to identify the most recent leaderboard entry – for which the user can enter their initials)

Store flashcard deck response to database

script name: record_qcard_v2
POST or GET variables Definition Value examples/alternatives Required?
(default)
qname Quiz/deck specifier qcard_ Required
i_qwiz Which quiz/deck on page 0
1		 Required
qwiz_session_id User login session ID 996971646 Required, must be non-expired
qrecord_id ID of quiz/deck for recording user responses dan_k-resonance-1 Required
qrecord__id_ok Check qrecord_id If set, check whether user is enrolled in class that has assigned (will give credit for) this flashcard deck Optional (default: qrecord_id not checked)
type Type of response start [should be sent when user begins going through a flashcard deck after a page load/reload]
flashcard [when user clicks “Got it” or “Need more practice” on a card]		 Required
first_flip_sec Unix time when card first flipped 1591470028 Required
now_sec Unix time when user clicked “Got it” or “Need more practice” 1591470052 Required
n_flips Number of flips front to back 2 Required
got_it_f Whether user clicked “Got it” or “Need more practice” 0 [“Need more practice”]
1 [“Got it”]		 Required
q_and_a_text Question and answer text, What question/card is being recorded?  base-64-encoded text, or dataset ID, or — in case of Phone App — plain-text dataset_id (e.g., testdeck2|1a32ffc7acbc1) Required, unless
type=start
i_card Number of card, or for dataset, dataset_id Which card in deck (non-datasets).  For dataset cards, use the card’s dataset_id (e.g., intro1-deck|2194cccaa6f394) Required, unless
type=start
unit Unit (category) name Which category in flashcard deck? Optional (default: none)
confirm Whether JSON structure returned json Optional (default: no response data)
app_version Which version of app used 2020_In_App_Purchase Optional (default: none)
Response
(when confirm=json): Array indexed by these variable names: qrecord_id, dataset_id, errmsg, ok (value 1 or 0)

Retrieve dataset units/topics counts

script name: get_dataset_units_topics
POST or GET variables Definition Value examples/alternatives Required?
(default)
dataset Dataset name AP_Bio_phone_App_DS Required
qname Quiz/deck specifier qwiz_
qcard_		 Required
i_qwiz_qdeck Which quiz or deck on page (quizzes/decks numbered separately) 0
1
…		 Required
qwiz_session_id Session ID for logged-in user 996971646 Optional (default: user not logged in, cannot indicate “questions correct so far”)
qrecord_id ID of quiz/deck for recording user responses dank-qwiz-conceptual-chemistry Optional (default: “questions correct” not available)
return Whether JSON structure returned instead of JavaScript code json Optional (default: JavaScript code)
topics Whether topic detail provided in JSON return 1 Option (default: topic detail not provide when return=json)
Response
(when return=json): Array indexed by these variable names:
qname qwiz_ or qcard_
i_qwiz_qdeck 0
qrecord_id Name under which responses recorded (if set)
dataset Dataset name
units Array of unit names corresponding to each element of arrays of number of questions remaining, etc.
topics Array of topic names corresponding to each element of arrays of number of questions remaining, etc.
n_questions_remainings Array of number of questions remaining by unit and topic (if qrecord_id set)
n_questions_by_unit_topic Array of number of questions available by unit and topic
n_correct_by unit_topic Array of number of questions answered correctly by unit and topic (if qrecord_id set; zeros if valid qwiz_session_id not provided)
n_incorrect_by unit_topic Array of number of questions answered incorrectly by unit and topic (if qrecord_id set; zeros if valid qwiz_session_id not provided)

Retrieve progress for selected quizzes/decks for a student

script name: get_selected_student_results
POST or GET variables Definition Value examples/alternatives Required?
(default)
session_id User login session ID 996971646 Required, must be non-expired
qrecord_ids Quiz/deck IDs (semicolon-separated) dank-quiz1;dank-quiz2;dank-deck5 Required
Response
Json dictionary object – errmsg: (empty = success); arrays qrecord_id, n_questions, n_attempted, n_correct: each array element corresponds to a quiz or deck.

Retrieve quiz-elapsed-time leaderboard data

script name: get_quiz_times
POST or GET variables Definition Value examples/alternatives Required?
(default)
qname Quiz/deck specifier qwiz_ Required
i_qwiz Which quiz on page 0
1		 Required
qwiz_session_id User login session ID 996971646 Required, must be non-expired
qrecord_id ID of quiz dan_k-functional-groups-1 Required
json Whether json structure returned instead of JavaScript code 1 Optional (default: JavaScript call to draw_histogram ())
Response
(when json=1): Array indexed by these variable names:
i_qwiz 0
i_takers Array of user IDs (anonymizing integers); the same ID may occur multiple times (multiple instances that user did the quiz)
initialss Array of initials for each user-quiz instance (may be unicode/emojis, but no more than three characters/emojis each)
dates Array of dates when users did quiz (Unix timestamp) for each user-quiz instance
times Array of elapsed times for each user-quiz instance
i_taker Integer ID of current user

Store user initials (leaderboard) to database

script name: update_quiz_elapsed_time
POST or GET variables Definition Value examples/alternatives Required?
(default)
qname Quiz/deck specifier qwiz_ Required
i_qwiz Which quiz on page 0 Required
qwiz_session_id User login session ID 996971646 Required, must be non-expired
quiz_elapsed_time_id ID ID of quiz elapsed time record; returned by record_quiz_time, above. Required
initials User initials R*S Required