WebQ REST API

Definitions

{version}: Refers to the version of the WebQ API desired.
{user}: Refers to a person's UWNetID
{survey_id}: Refers to the numeric ID of the survey in question.
[...]: Content within square brackets is optional when constructing URIs.

Resources

/webq

GET: Returns an XHTML payload listing all available version of this resource.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>Versions</title>
    </head>
    <body>
        <h1>Versions</h1>
        <ul class="versions">
           <li><a class="version" href="https://example.washington.edu/tools/rest/webq/v1/survey">v1</a></li>
        </ul>
    </body>
</html>

GET: Returns an XHTML payload listing all users having webqs that the currently authenticated client is authorized to view.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>Survey
list</title>
    </head>
    <body>
        <h1>Survey list</h1>
        <ul class="surveys">
            <li>
               <a class="survey" href="https://example.washington.edu/tools/rest/webq/v1/survey/4579">Aardvark Quiz</a>
<span class="response_count">0</span> responses
            </li>
            <li>
               <a class="survey" href="https://example.washington.edu/tools/rest/webq/v1/survey/4293">Apple Quiz</a>
               <span class="response_count">12</span> responses
            </li>
            <li>
               <a class="survey" href="https://example.washington.edu/tools/rest/webq/v1/survey/4569">Zebra Satisfaction Survey</a>
               <span class="response_count">0</span> responses
            </li>
        </ul>
    </body>
</html>

/webq/{version}/survey/{survey_id}

GET: Returns an XHTML payload linking to survey details.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>Apple Quiz</title>
    </head>
    <body class="survey">
        <h1 class="title">Apple Quiz</h1>
        <div>
            <a rel="survey_list" href="https://example.washington.edu/tools/rest/webq/v1/survey">Survey list</a>
        </div>
        <br/>
        <div>
            <a rel="start_survey" href="https://example.washington.edu/tools/webq/survey/mcrawfor/3767">Begin survey</a>
            <br/>
            <a rel="participants" href="https://example.washington.edu/tools/rest/webq/v1/survey/3767/participants">Participants</a>
            <br/>
            <a rel="questions" href="https://example.washington.edu/tools/rest/webq/v1/survey/3767/questions">Questions</a>
            <br/>
            <a rel="responses" href="https://example.washington.edu/tools/rest/webq/v1/survey/3767/responses">
            <span class="response_count">12</span> responses</a>
        </div>
    </body>
</html>

/webq/{version}/survey/{survey_id}/participants

GET: Returns an XHTML payload describing the current list of participants authorized by the REST API. This includes ONLY participants authorized by the REST API. Participants allowed via other methods will not appear here, thus the results resource may include responses from participants not listed here.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>Participants for Apple Quiz</title>
    </head>
    <body class="participants">
        <h1>Participants for Apple Quiz</h1>
        <div>
            <a rel="survey" class="title" href="https://example.washington.edu/tools/rest/webq/v1/survey/3767">Apple Quiz</a>
            <h2>Participants</h2>
            <ul class="participants">
                <li class="participant">
                    <a class="rest_id" rel="personal_url" href="https://example.washington.edu/tools/webq/survey/mcrawfor/3767/e70346fa9b21887bb72650c79ced6ff7">214007523</a>
                    <span class="reponse_count">0</span> responses
                </li>
                <li class="participant">
                    <a class="rest_id" rel="personal_url" href="https://example.washington.edu/tools/webq/survey/mcrawfor/3767/a4808af1392f4ff73137ba15181c039b">example_id</a>
                    <span class="reponse_count">1</span> responses
                </li>
            </ul>
        </div>
    </body>
</html>

Note that a return_url query string can be added to the personal_url to bring a participant to a particular place after completing the survey. For example:

https://example.washington.edu/tools/webq/survey/mcrawfor/3767/a65ds46b54a?return_url=http://google.com

This allows the survey to be used as a component in another web application.

POST: Creates a new participant who is authorized to take the survey. Optional request body contains any XML/XHTML representation of the participant including any element classed as the desired participant REST ID:

<element class="rest_id">example_id</element>

This will fail unless the survey security is either unset or set to "Anonymous," in order to protect existing authentication settings. Once you have added one or more participants via the REST API the survey is only available to these REST participants.

Returns an XHTML payload describing the new user:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
      <title>New Participant</title>
    </head>
    <body class="participant">
        <div>
            <a class="rest_id" rel="personal_url" href="https://example.washington.edu/tools/webq/survey/mcrawfor/3767/72c79c5c6fbd821d86f6f807febcfe42">moo</a>
        </div>
    </body>
</html>

/webq/{version}/survey/{survey_id}/responses[?rest_id=example&participant_id=1234&...]

GET: Returns an XHTML payload listing responses for {survey_id}. With no parameters this resource will return all the responses for a survey. Any number of rest_id or participant_id parameters may be provided to narrow the results returned. The two types of IDs are applied as filters, so if both REST IDs and participant IDs are provided only the overlap will be returned. Each type of ID is additive, however, so three participant IDs will return results for three participants.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>Responses for Apple Quiz</title>
    </head>
    <body>
        <h1>Responses for Apple Quiz</h1>
        <div>
            <a class="title" rel="survey" href="https://example.washington.edu/tools/rest/webq/v1/survey/3767">Apple Quiz</a>
        </div>
        <h2>Questions</h2>
        <ul class="questions">
            <li class="question">
                <span class="question_id">761739</span> 
                <div>Question type: <span class="type">Matrix - one answer per row (button)</span></div>
                <div>Question content: <span class="content">Apple Matchup</span></div>
                Rows:
                <ul class="rows">
                    <li class="prompt">Red</li>
                    <li class="prompt">Green</li>
                    <li class="prompt">Mixed</li>
                </ul>
                Options:
                <ul class="options">
                    <li class="option">Granny Smith</li>
                    <li class="option">Red Delicious</li>
                    <li class="option">Fuji</li>
                </ul>
            </li>
        </ul>
        <h2>Participants</h2>
        <ul class="participants">
            <li class="participant">
                Participant ID: <span class="participant_id">398</span><br/>
                REST ID: <span class="rest_id">230241206</span><br/>
                Start Date:<span class="start_date">2007-11-06 10:12:09</span><br/>
                End Date:<span class="end_date">2007-11-06 11:01:09</span><br/>
                <ul class="responses">
                     <li class="response">
                         Response ID:<span class="response_id">433</span><br/>
                         <span class="question_id">761739</span><br/>
                         <ul class="rows">
                             <li class="row">
                                 Possible points:<span>2.66666666666667</span><br/>
                                 Score:<span class="score">0</span><br/>
                             </li>
                             <li class="row">
                                 Possible points:<span>2.66666666666667</span><br/>
                                 Score:<span class="score">0</span><br/>
                                 Text values:
                                 <ul class="text_values">
                                      <li class="text_value">1</li>
                                 </ul>
                                 Numeric values:
                                 <ul class="numeric_values">
                                      <li class="numeric_value">1</li>
                                 </ul>
                             </li>
                             <li class="row">
                                 Possible points:<span>2.66666666666667</span><br/>
                                 Score:<span class="score">0</span><br/>
                                 Text values:
                                 <ul class="text_values">
                                     <li class="text_value">1</li>
                                 </ul>
                                 Numeric values:
                                 <ul class="numeric_values">
                                     <li class="numeric_value">1</li>
                                 </ul>
                             </li>
                         </ul>        
                     </li>
                 </ul>
            </li>
        </ul>
    </body>
</html>